Querying Users
Confused about "Querying Users"?
Let us know how we can improve our documentation:
- On This Page:
- Querying Using the $autocomplete Operator
The Query Users method allows you to search for users and see if they are online/offline. The example below shows how you can retrieve the details for 3 users in one API call:
1
const response = await client.queryUsers({ id: { $in: ['john', 'jack', 'jessie'] } });
1
2
3
4
5
6
7
8
9
10
11
12
13
// Search users with id "john", "jack", or "jessie"
FilterObject filter = Filters.in("id", Arrays.asList("john", "jack", "jessie"));
int offset = 0;
int limit = 3;
QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit);
client.queryUsers(request).enqueue(result -> {
if (result.isSuccess()) {
List<User> users = result.data();
} else {
// Handle result.error()
}
});
1
2
3
4
5
6
7
8
9
10
11
12
13
let controller = chatClient.userListController(
query: .init(filter: .in(.id, values: ["john", "jack", "jessie"]))
)
controller.synchronize { error in
if let error = error {
// handle error
print(error)
} else {
// access users
print(controller.users)
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Search for users with id "john", "jack", or "jessie"
val request = QueryUsersRequest(
filter = Filters.`in`("id", listOf("john", "jack", "jessie")),
offset = 0,
limit = 3,
)
client.queryUsers(request).enqueue { result ->
if (result.isSuccess) {
val users: List<User> = result.data()
} else {
// Handle result.error()
}
}
1
$response = $client->queryUsers([ 'id' => ['$in' => ['john', 'jack', 'jessie'] ] ]);
1
2
3
4
5
6
7
final _result = client.queryUsers(
filter: {
"id": {
"\$in": ['john', 'jack', 'jessie']
}
},
);
1
2
3
4
5
const response = await client.queryUsers(
{ id: { $in: ['jessica'] } },
{ last_active: -1},
{ presence: true },
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
let controller = chatClient.userListController(
query: .init(
filter: .in(.id, values: ["john", "jack", "jessie"]),
sort: [.init(key: .lastActivityAt, isAscending: false)]
)
)
controller.synchronize { error in
if let error = error {
// handle error
print(error)
} else {
// access users
print(controller.users)
}
}
// load more if needed
controller.loadNextUsers(limit: 10) { error in
// handle error / access users
}
1
2
3
4
5
$response = $client->queryUsers(
[
'id' => ['$in' => ['john', 'jack', 'jessie'] ],
'last_active' => '2019-11-05T21:35:24.397995Z',
]);
1
2
3
4
5
6
7
8
9
10
11
12
final _result = client.queryUsers(
filter: {
"id": {
"\$in": ['john', 'jack', 'jessie']
}
},
sort: [SortOption('last_active')],
pagination: PaginationParams(
offset: 0,
limit: 20,
),
);
Another option is to query for banned
users. This can be done with the following code snippet:
1
const banned = await client.queryUsers({ id: 'jessica', banned: true });
1
2
3
4
5
$banned = $client->queryUsers(
[
'id' => 'bob-1',
'banned' => true,
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
let controller = chatClient.userListController(
query: .init(
filter: .equal(.isBanned, to: true),
sort: [.init(key: .lastActivityAt, isAscending: false)]
)
)
controller.synchronize { error in
if let error = error {
// handle error
print(error)
} else {
// access users
print(controller.users)
}
}
1
2
3
4
5
6
7
val request = QueryUsersRequest(
filter = Filters.eq("banned", true),
offset = 0,
limit = 10,
)
client.queryUsers(request).enqueue { /* ... */ }
1
2
3
4
5
6
FilterObject filter = Filters.eq("banned", true);
int offset = 0;
int limit = 10;
QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit);
client.queryUsers(request).enqueue(result -> { /* ... */ });
1
2
3
4
5
6
7
8
9
10
11
final _result = client.queryUsers(
filter: {
"id": "jessie",
"banned": true,
},
sort: [SortOption('last_active')],
pagination: PaginationParams(
offset: 0,
limit: 20,
),
);
An object with an array of users will be returned.
You can filter and sort on the custom fields you've set for your user, the user id, and when the user was last active.
The options for the queryUser
method are presence
, limit
, and offset
. If presence
is true
this makes sure you receive the user.presence.changed
event when a user goes online or offline.
name | type | description | default | optional |
---|---|---|---|---|
presence | boolean | Get updates when the user goes offline/online | false | ✓ |
limit | integer | Number of users to return | 30 | ✓ |
offset | integer | Offset for pagination | 0 | ✓ |
Querying Using the $autocomplete Operator
Copied!Confused about "Querying Using the $autocomplete Operator"?
Let us know how we can improve our documentation:
You can autocomplete the results of your user query by username and/or ID.
1. By Username
Copied!Confused about "1. By Username"?
Let us know how we can improve our documentation:
If you want to return all users whose username includes 'ro'
, you could do so with the following:
1
const response = await serverClient.queryUsers({ name: { $autocomplete: 'ro' } });
1
2
3
4
$response = $client->queryUsers(
[
'name' => ['$autocomplete' => 'ro']
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
let controller = chatClient.userListController(
query: .init(filter: .autocomplete(.name, text: "ro"))
)
controller.synchronize { error in
if let error = error {
// handle error
print(error)
} else {
// access users
print(controller.users)
}
}
1
2
3
4
5
6
FilterObject filter = Filters.autocomplete("name", "ro");
int offset = 0;
int limit = 10;
QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit);
client.queryUsers(request).enqueue(result -> { /* ... */ });
1
2
3
4
5
6
7
val request = QueryUsersRequest(
filter = Filters.autocomplete("name", "ro"),
offset = 0,
limit = 10,
)
client.queryUsers(request).enqueue { /* ... */ }
1
2
3
4
5
6
7
final _result = client.queryUsers(
filter: {
"name": {
"\$autocomplete": "ro"
},
},
);
This would return an array of any matching users, such as:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
{
"id": "userID",
"name": "Curiosity Rover"
},
{
"id": "userID2",
"name": "Roxy"
},
{
"id": "userID3",
"name": "Roxanne"
}
]
2. By ID
Copied!Confused about "2. By ID"?
Let us know how we can improve our documentation:
1
const response = await client.queryUsers({ id: { $autocomplete: 'USER_ID' } });
1
2
3
4
$response = $client->queryUsers(
[
'id' => ['$autocomplete' => 'user-id']
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
let controller = chatClient.userListController(
query: .init(filter: .autocomplete(.id, text: "ro"))
)
controller.synchronize { error in
if let error = error {
// handle error
print(error)
} else {
// access users
print(controller.users)
}
}
1
2
3
4
5
6
FilterObject filter = Filters.autocomplete("id", "USER_ID");
int offset = 0;
int limit = 10;
QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit);
client.queryUsers(request).enqueue(result -> { /* ... */ });
1
2
3
4
5
6
7
val request = QueryUsersRequest(
filter = Filters.autocomplete("id", "USER_ID"),
offset = 0,
limit = 10,
)
client.queryUsers(request).enqueue { /* ... */ }
1
2
3
4
5
6
7
final _result = client.queryUsers(
filter: {
"id": {
"\$autocomplete": "USER_ID"
},
},
);