Query Members

Last Edit: Nov 27 2020

Sometimes channels will have many hundreds (or thousands) of members and it is important to be able to access ID's and information on all of these members. The queryMembers endpoint queries the channel members and allows the user to paginate through a full list of users in channels with very large member counts. The endpoint supports filtering on numerous criteria to efficiently return member information.

The members are sorted by created_at in ascending order.
Stream Chat does not run MongoDB on the backend, only a subset of the query options are available.

Here’s some example of how you can query the list of members:


// query members by user.name
const {members} = await channel.queryMembers({'name':'tommaso'})
console.log(members)

// query members with name containing tom
channel.queryMembers({name:{"$q":'tom'}})

// autocomplete members by user name
channel.queryMembers({name:{"$autocomplete":'tomm'}})

// query member by id
channel.queryMembers({id:'tommaso'})

// query multiple members by id
channel.queryMembers({id:{'$in:'['tommaso','thierry']}})

// query channel moderators
channel.queryMembers({is_moderator:true})

// query for banned members in channel
channel.queryMembers({banned:true})

// query members with pending invites
channel.queryMembers({invite:'pending'})

// query all the members 
channel.queryMembers({})

// paginate channel members
channel.queryMembers({}, {}, {limit:10,offset:10})

// order results by member created at descending
channel.queryMembers({}, {created_at:-1})
                    

let channel = Client.shared.channel(type: .messaging, id: "general")

// query members by user.name
channel.queryMembers(filter: .equal("name", to: "tommaso")) { (result) in
    print(result)
}

// query members with name containing tom
channel.queryMembers(filter: .query("name", with: "tom")) { (result) in
    print(result)
}

// autocomplete members by user name
channel.queryMembers(filter: .autocomplete("name", with: "tom")) { (result) in
    print(result)
}

// query member by id
channel.queryMembers({id:'tommaso'})
channel.queryMembers(filter: .equal("id", to: "tommaso")) { (result) in
    print(result)
}

// query multiple members by id
channel.queryMembers(filter: .in("id", ["tommaso", "thierry"])) { (result) in
    print(result)
}

// query channel moderators
channel.queryMembers(filter: .equal("is_moderator", to: true)) { (result) in
    print(result)
}

// query for banned members in channel
channel.queryMembers(filter: .equal("banned", to: true)) { (result) in
    print(result)
}

// query members with pending invites
channel.queryMembers(filter: .equal("invite", to: "pending")) { (result) in
    print(result)
}

// query all the members 
channel.queryMembers({})
channel.queryMembers(filter: .none) { (result) in
    print(result)
}

// paginate channel members
channel.queryMembers(limit: 10, offset: 10) { (result) in
    print(result)
}

// order results by member created at descending
channel.queryMembers(sorting: [Sorting("created_at", isAscending: false)]) { (result) in
    print(result)
}
                    

# query members by user.name
response = channel.query_members(
            filter_conditions={"name": "tommaso"},
            sort=[{"field": "created_at", "direction": 1}],
            offset=1,
            limit=10,
        )

# query members with name containing tom
response = channel.query_members( filter_conditions={"name": {"$q": "tom"}} )

# autocomplete members by user name
response = channel.query_members( filter_conditions={"name": {"$autocomplete": "tomm"}} )

# query member by id
response = channel.query_members( filter_conditions={"id": "tommaso"} )

# query multiple members by id
response = channel.query_members( filter_conditions={"id": {"$in":['tommaso','thierry']}} )

# query channel moderators
response = channel.query_members( filter_conditions={"is_moderator": True} )

# query for banned members in channel
response = channel.query_members( filter_conditions={"banned": True})

# query members with pending invites
response = channel.query_members( filter_conditions={"invite": "pending"} )
                    

Query Parameters

Name Type Description Default Optional
filters object The query filters to use. You can query on any of the custom fields defined above {}
sort object the sort parameters { created_at:1}
options object pagination options { limit:100, offset:0}
By default when query members does not have any filter and it will match all members on your channel.

Member Queryable Built-In Fields

The following channel fields can be used to filter your query results

Name Type Description Example
id string the id of the user tom
name string the name of the user Tommaso
is_moderator boolean the member role true
banned boolean the banned status false
invite string, must be one of these values: (pending, accepted, rejected) the status of the invite pending

Query Options

Name Type Description Default Optional
limit integer The number of members to return (max is 100) 100
offset integer The offset (max is 10000) 0

Response

The result of query Members is a  QueryMembersResponse object which include all the matched members within the limit

QueryMembersResponse

Field Name Description
members The list of members, up to 100 ordered by the most recent added