Metadata API for PubNub Swift Native SDK
This page describes the new Objects v2. To upgrade from Objects v1, refer to the migration guide.
Note
The PubNub Swift 3.0 SDK contains many significant changes from the 2.x SDK, including breaking changes. Please refer to the PubNub Swift 3.0 Migration Guide for more details.
Objects provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use Objects to easily store metadata about your application users and channels, and their membership associations, without the need to stand up your own databases.
PubNub also triggers events when object data is set or removed from the database. Clients can receive these events in real-time and update their front-end application accordingly.
User
Get Metadata for All Users
Description
Returns a paginated list of UUID Metadata objects, optionally including the custom data object for each.
Method(s)
To Get All UUID Metadata
you can use the following method(s) in the Swift SDK:
allUUIDMetadata( include: IncludeFields = IncludeFields(), filter: String? = nil, sort: [ObjectSortField] = [], limit: Int? = 100, page: PubNubHashedPage? = Page(), custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<(uuids: [PubNubUUIDMetadata], next: PubNubHashedPage?), Error>) -> Void)?)
Parameter Type Required Defaults Description include
IncludeFields Optional IncludeFields()
Whether to include the custom field in the fetch response filter
String? Optional nil
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here sort
[ObjectSortField] Optional []
List of properties to sort response objects. The following properties are valid for sorting: .id
,.name
, and.updated
.page
PubNubHashedPage? Optional PubNub.Page()
The paging object used for pagination limit
Int? Optional 100 The number of objects to retrieve at a time custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<(uuids: [PubNubUUIDMetadata], next: PubNubHashedPage?), Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success A
Tuple
containing anArray
ofPubNubUUIDMetadata
, and the next paginationPubNubHashedPage
(if one exists).public protocol PubNubUUIDMetadata { /// The unique identifier of the UUID var metadataId: String { get } /// The name of the UUID var name: String { get set } /// The external identifier for the object var externalId: String? { get set } /// The profile URL for the object var profileURL: String? { get set } /// The email address of the object var email: String? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
public protocol PubNubHashedPage { /// The hash value representing the next set of data var start: String? { get } /// The hash value representing the previous set of data var end: String? { get } /// The total count of all objects withing range var totalCount: Int? { get } }
Failure An
Error
describing the failure.
Basic Usage
pubnub.allUUIDMetadata() { result in
switch result {
case let .success(response):
print("The uuid metadata objects \(response.uuids)")
if let nextPage = response.next {
print("The next page used for pagination: \(nextPage)")
}
case let .failure(error):
print("Fetch All request failed with error: \(error.localized### Description)")
}
}
Get User Metadata
Description
Returns metadata for the specified UUID, optionally including the custom data object for each.
Method(s)
To Get UUID Metadata
you can use the following method(s) in the Swift SDK:
fetch( uuid metadata: String?, include customFields: Bool = true, custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<PubNubUUIDMetadata, Error>) -> Void)?)
Parameter Type Required Defaults Description uuid
String Yes Unique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration include
IncludeFields Optional IncludeFields()
Whether to include the custom field in the fetch response custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<PubNubUUIDMetadata, Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success The
PubNubUUIDMetadata
object belonging to the identifier.public protocol PubNubUUIDMetadata { /// The unique identifier of the UUID var metadataId: String { get } /// The name of the UUID var name: String { get set } /// The external identifier for the object var externalId: String? { get set } /// The profile URL for the object var profileURL: String? { get set } /// The email address of the object var email: String? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
Failure An
Error
describing the failure.
Basic Usage
pubnub.fetch(uuid: "TestUser") { result in
switch result {
case let .success(uuidMetadata):
print("The metadata for `\(uuidMetadata.metadataId)`: \(uuidMetadata)")
case let .failure(error):
print("Fetch request failed with error: \(error.localized### Description)")
}
}
Set User Metadata
Description
Set metadata for a UUID in the database, optionally including the custom data object for each.
Method(s)
To Set UUID Metadata
you can use the following method(s) in the Swift SDK:
set( uuid metadata: PubNubUUIDMetadata, include customFields: Bool = true, custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<PubNubUUIDMetadata, Error>) -> Void)?)
Parameter Type Required Defaults Description uuid
PubNubUUIDMetadata Yes UUID Metadata to set. include
IncludeFields Optional IncludeFields()
Whether to include the custom field in the fetch response. custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session. Objects filtering language doesn’t support filtering by custom properties. completion
((Result<PubNubUUIDMetadata, Error>) -> Void)? Optional nil
The async Result
of the method call.
Completion Handler Result
Success The
PubNubUUIDMetadata
object belonging to the identifier.public protocol PubNubUUIDMetadata { /// The unique identifier of the UUID var metadataId: String { get } /// The name of the UUID var name: String { get set } /// The external identifier for the object var externalId: String? { get set } /// The profile URL for the object var profileURL: String? { get set } /// The email address of the object var email: String? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
Failure An
Error
describing the failure.
Basic Usage
let johnDoe = PubNubUUIDMetadataBase(
id: "john-doe", name: "John Doe",
custom: ["title": "Mr. Manager"]
)
pubnub.set(user: johnDoe) { result in
switch result {
case let .success(uuidMetadata):
print("The metadata for `\(uuidMetadata.metadataId)`: \(uuidMetadata)")
case let .failure(error):
print("Create request failed with error: \(error.localized### Description)")
}
}
Remove User Metadata
Description
Removes the metadata from a specified UUID.
Method(s)
To Remove UUID Metadata
you can use the following method(s) in the Swift SDK:
remove( uuid metadataId: String?, custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<String, Error>) -> Void)?)
Parameter Type Required Defaults Description uuid
String Yes Unique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<PubNubUUIDMetadata, Error>) -> Void)? Optional nil
The async Result
of the method call
Basic Usage
pubnub.remove(uuid: "john-doe") { result in
switch result {
case let .success(metadataId):
print("The metadata has been removed for the uuid `\(metadataId)`")
case let .failure(error):
print("Delete request failed with error: \(error.localized### Description)")
}
}
Channel
Get Metadata for All Channels
Description
Returns a paginated list of Channel Metadata objects, optionally including the custom data object for each.
Method(s)
To Get All Channel Metadata
you can use the following method(s) in the Swift SDK:
allChannelMetadata( include: IncludeFields = IncludeFields(), filter: String? = nil, sort: [ObjectSortField] = [], limit: Int? = 100, page: PubNubHashedPage? = Page(), custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<(uuids: [PubNubChannelMetadata], next: PubNubHashedPage?), Error>) -> Void)?)
Parameter Type Required Defaults Description include
IncludeFields Optional IncludeFields()
Whether to include the custom field in the fetch response filter
String? Optional nil
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here sort
[ObjectSortField] Optional []
List of properties to sort response objects. The following properties are valid for sorting: .id
,.name
, and.updated
.limit
Int? Optional 100 The number of objects to retrieve at a time page
PubNubHashedPage? Optional PubNub.Page()
The paging object used for pagination custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<(channels: [PubNubChannelMetadata], next: PubNubHashedPage?), Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success A
Tuple
containing anArray
ofPubNubChannelMetadata
, and the next paginationPubNubHashedPage
(if one exists).public protocol PubNubChannelMetadata { /// The unique identifier of the Channel var metadataId: String { get } /// The name of the Channel var name: String { get set } /// Text describing the purpose of the channel var channelDescription: String? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
public protocol PubNubHashedPage { /// The hash value representing the next set of data var start: String? { get } /// The hash value representing the previous set of data var end: String? { get } /// The total count of all objects withing range var totalCount: Int? { get } }
Failure An
Error
describing the failure.
Basic Usage
pubnub.allChannelMetadata() { result in
switch result {
case let .success(response):
print("The channel metadata objects \(response.channels)")
if let nextPage = response.next {
print("The next page used for pagination: \(nextPage)")
}
case let .failure(error):
print("Fetch All request failed with error: \(error.localized### Description)")
}
}
Get Channel Metadata
Description
Returns metadata for the specified Channel, optionally including the custom data object for each.
Method(s)
To Get Channel Metadata
you can use the following method(s) in the Swift SDK:
fetch( channel metadata: String?, include customFields: Bool = true, custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<PubNubChannelMetadata, Error>) -> Void)?)
Parameter Type Required Defaults Description channel
String Yes Unique Channel Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration include
IncludeFields Optional IncludeFields()
Whether to include the custom field in the fetch response custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<PubNubChannelMetadata, Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success The
PubNubChannelMetadata
object belonging to the identifier.public protocol PubNubChannelMetadata { /// The unique identifier of the Channel var metadataId: String { get } /// The name of the Channel var name: String { get set } /// Text describing the purpose of the channel var channelDescription: String? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
Failure An
Error
describing the failure.
Basic Usage
pubnub.fetch(channel: "TestUser") { result in
switch result {
case let .success(channelMetadata):
print("The metadata for `\(channelMetadata.metadataId)`: \(channelMetadata)")
case let .failure(error):
print("Fetch request failed with error: \(error.localized### Description)")
}
}
Set Channel Metadata
Description
Set metadata for a Channel in the database, optionally including the custom data object for each.
Method(s)
To Set Channel Metadata
you can use the following method(s) in the Swift SDK:
set( channel metadata: PubNubChannelMetadata, include customFields: Bool = true, custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<PubNubChannelMetadata, Error>) -> Void)?)
Parameter Type Required Defaults Description channel
PubNubChannelMetadata Yes Channel Metadata to set. include
IncludeFields Optional IncludeFields()
Whether to include the custom field in the fetch response. custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session. Objects filtering language doesn’t support filtering by custom properties. completion
((Result<PubNubChannelMetadata, Error>) -> Void)? Optional nil
The async Result
of the method call.
Completion Handler Result
Success The
PubNubChannelMetadata
object belonging to the identifier.public protocol PubNubChannelMetadata { /// The unique identifier of the Channel var metadataId: String { get } /// The name of the Channel var name: String { get set } /// Text describing the purpose of the channel var channelDescription: String? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
Failure An
Error
describing the failure.
Basic Usage
let johnDoe = PubNubChannelMetadataBase(
id: "john-doe", name: "John Doe",
custom: ["title": "Mr. Manager"]
)
pubnub.set(user: johnDoe) { result in
switch result {
case let .success(channelMetadata):
print("The metadata for `\(channelMetadata.metadataId)`: \(channelMetadata)")
case let .failure(error):
print("Create request failed with error: \(error.localized### Description)")
}
}
Remove Channel Metadata
Description
Removes the metadata from a specified channel.
Method(s)
To Remove Channel Metadata
you can use the following method(s) in the Swift SDK:
remove( channel metadataId: String?, custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<String, Error>) -> Void)?)
Parameter Type Required Defaults Description channel
String Yes Unique Channel Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<PubNubChannelMetadata, Error>) -> Void)? Optional nil
The async Result
of the method call
Basic Usage
pubnub.remove(channel: "john-doe") { result in
switch result {
case let .success(metadataId):
print("The metadata has been removed for the channel `\(metadataId)`")
case let .failure(error):
print("Delete request failed with error: \(error.localized### Description)")
}
}
Channel Memberships
Get Channel Memberships
Description
The method returns a list of channel memberships for a user. This method doesn't return a user's subscriptions.
Method(s)
To Get Memberships
you can use the following method(s) in the Swift SDK:
To Get Channel Memberships
you can use the following method(s) in the Swift SDK:
fetchMemberships( uuid: String?, include: MembershipInclude = MembershipInclude(), filter: String? = nil, sort: [MembershipSortField] = [], limit: Int? = 100, page: PubNubHashedPage? = Page(), custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
Parameter Type Required Defaults Description uuid
String Yes Unique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration include
MembershipInclude Optional MembershipInclude()
Whether to include the custom field in the fetch response filter
String? Optional nil
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here sort
[MembershipSortField] Optional []
List of properties to sort response objects. The following properties are valid for sorting: .object(.id)
,.object(.name)
,.object(.updated)
, and.updated
.limit
Int? Optional 100 The number of objects to retrieve at a time page
PubNubHashedPage? Optional PubNub.Page()
The paging object used for pagination custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success A
Tuple
containing anArray
ofPubNubMembershipMetadata
, and the next paginationPubNubHashedPage
(if one exists).public protocol PubNubMembershipMetadata { /// The unique identifier of the associated UUID var uuidMetadataId: String { get } /// The unique identifier of the associated Channel var channelMetadataId: String { get } /// The associated UUID metadata var uuid: PubNubUUIDMetadata? { get set } /// The associated Channel metadata var channel: PubNubChannelMetadata? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
public protocol PubNubHashedPage { /// The hash value representing the next set of data var start: String? { get } /// The hash value representing the previous set of data var end: String? { get } /// The total count of all objects withing range var totalCount: Int? { get } }
Failure An
Error
describing the failure.
Basic Usage
pubnub.fetchMemberships(uuid: "my_user") { result in
switch result {
case let .success(response):
print("The channel memberships for the uuid \(response.memberships)")
if let nextPage = response.next {
print("The next page used for pagination: \(nextPage)")
}
case let .failure(error):
print("Fetch Memberships request failed with error: \(error.localized### Description)")
}
}
Set Channel Memberships
Description
Set channel memberships for a UUID.
Method(s)
To Set Channel Memberships
you can use the following method(s) in the Swift SDK:
setMemberships( uuid metadataId: String?, channels memberships: [PubNubMembershipMetadata], include: MembershipInclude = MembershipInclude(), filter: String? = nil, sort: [MembershipSortField] = [], limit: Int? = 100, page: PubNubHashedPage? = Page(), custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
Parameter Type Required Defaults Description uuid
String Yes Unique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration channels
[PubNubMembershipMetadata] Yes Array of PubNubMembershipMetadata
with thePubNubChannelMetadata
orchannelMetadataId
providedinclude
MembershipInclude Optional MembershipInclude()
Whether to include the custom field in the fetch response filter
String? Optional nil
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here sort
[MembershipSortField] Optional []
List of properties to sort response objects. The following properties are valid for sorting: .object(.id)
,.object(.name)
,.object(.updated)
, and.updated
.limit
Int? Optional 100 The number of objects to retrieve at a time page
PubNubHashedPage? Optional PubNub.Page()
The paging object used for pagination custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success A
Tuple
containing anArray
ofPubNubMembershipMetadata
, and the next paginationPubNubHashedPage
(if one exists).public protocol PubNubMembershipMetadata { /// The unique identifier of the associated UUID var uuidMetadataId: String { get } /// The unique identifier of the associated Channel var channelMetadataId: String { get } /// The associated UUID metadata var uuid: PubNubUUIDMetadata? { get set } /// The associated Channel metadata var channel: PubNubChannelMetadata? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
public protocol PubNubHashedPage { /// The hash value representing the next set of data var start: String? { get } /// The hash value representing the previous set of data var end: String? { get } /// The total count of all objects withing range var totalCount: Int? { get } }
Failure An
Error
describing the failure.
Basic Usage
let newMembership = PubNubMembershipMetadataBase(
uuidMetadataId: "my_user", channelMetadataId: "my_channel"
)
pubnub.setMemberships(
uuid: newMembership.uuidMetadataId,
channels: [newMembership]
) { result in
switch result {
case let .success(response):
print("The channel memberships for the uuid \(response.memberships)")
if let nextPage = response.next {
print("The next page used for pagination: \(nextPage)")
}
case let .failure(error):
print("Update Memberships request failed with error: \(error.localized### Description)")
}
}
Remove Channel Memberships
Description
Remove channel memberships for a UUID.
Method(s)
To Remove Channel Memberships
you can use the following method(s) in the Swift SDK:
removeMemberships( uuid metadataId: String?, channels memberships: [PubNubMembershipMetadata], include: MembershipInclude = MembershipInclude(), filter: String? = nil, sort: [MembershipSortField] = [], limit: Int? = 100, page: PubNubHashedPage? = Page(), custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
Parameter Type Required Defaults Description uuid
String Yes Unique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration channels
[PubNubMembershipMetadata] Yes Array of PubNubMembershipMetadata
with thePubNubChannelMetadata
orchannelMetadataId
providedinclude
MembershipInclude Optional MembershipInclude()
Whether to include the custom field in the fetch response filter
String? Optional nil
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here sort
[MembershipSortField] Optional []
List of properties to sort response objects. The following properties are valid for sorting: .object(.id)
,.object(.name)
,.object(.updated)
, and.updated
.limit
Int? Optional 100 The number of objects to retrieve at a time page
PubNubHashedPage? Optional PubNub.Page()
The paging object used for pagination custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success A
Tuple
containing anArray
ofPubNubMembershipMetadata
, and the next paginationPubNubHashedPage
(if one exists).public protocol PubNubMembershipMetadata { /// The unique identifier of the associated UUID var uuidMetadataId: String { get } /// The unique identifier of the associated Channel var channelMetadataId: String { get } /// The associated UUID metadata var uuid: PubNubUUIDMetadata? { get set } /// The associated Channel metadata var channel: PubNubChannelMetadata? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
public protocol PubNubHashedPage { /// The hash value representing the next set of data var start: String? { get } /// The hash value representing the previous set of data var end: String? { get } /// The total count of all objects withing range var totalCount: Int? { get } }
Failure An
Error
describing the failure.
Basic Usage
let oldMembership = PubNubMembershipMetadataBase(
uuidMetadataId: "my_user", channelMetadataId: "my_channel"
)
pubnub.removeMemberships(
uuid: oldMembership.uuidMetadataId,
channels: [oldMembership]
) { result in
switch result {
case let .success(response):
print("The channel memberships for the uuid \(response.memberships)")
if let nextPage = response.next {
print("The next page used for pagination: \(nextPage)")
}
case let .failure(error):
print("Update Memberships request failed with error: \(error.localized### Description)")
}
}
Channel Members
Get Channel Members
Description
The method returns a list of members in a channel. The list will include user metadata for members that have additional metadata stored in the database.
Method(s)
To Get Channel Members
you can use the following method(s) in the Swift SDK:
fetchMembers( channel: String?, include: MemberInclude = MemberInclude(), filter: String? = nil, sort: [MembershipSortField] = [], limit: Int? = 100, page: PubNubHashedPage? = Page(), custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
Parameter Type Required Defaults Description channel
String Yes Unique Channel Metadata identifier include
MemberInclude Optional MemberInclude()
Whether to include the custom field in the fetch response filter
String? Optional nil
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here sort
[MembershipSortField] Optional []
List of properties to sort response objects. The following properties are valid for sorting: .object(.id)
,.object(.name)
,.object(.updated)
, and.updated
.limit
Int? Optional 100 The number of objects to retrieve at a time page
PubNubHashedPage? Optional PubNub.Page()
The paging object used for pagination custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success A
Tuple
containing anArray
ofPubNubMembershipMetadata
, and the next paginationPubNubHashedPage
(if one exists).public protocol PubNubMembershipMetadata { /// The unique identifier of the associated UUID var uuidMetadataId: String { get } /// The unique identifier of the associated Channel var channelMetadataId: String { get } /// The associated UUID metadata var uuid: PubNubUUIDMetadata? { get set } /// The associated Channel metadata var channel: PubNubChannelMetadata? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
public protocol PubNubHashedPage { /// The hash value representing the next set of data var start: String? { get } /// The hash value representing the previous set of data var end: String? { get } /// The total count of all objects withing range var totalCount: Int? { get } }
Failure An
Error
describing the failure.
Basic Usage
pubnub.fetchMembers(channel: "my_channel") { result in
switch result {
case let .success(response):
print("The uuid members for the channel \(response.memberships)")
if let nextPage = response.next {
print("The next page used for pagination: \(nextPage)")
}
case let .failure(error):
print("Fetch Memberships request failed with error: \(error.localized### Description)")
}
}
Set Channel Members
Description
This method sets members in a channel.
Method(s)
To Set Channel Members
you can use the following method(s) in the Swift SDK:
setMembers( channel metadataId: String, uuids members: [PubNubMembershipMetadata], include: MemberInclude = MemberInclude(), filter: String? = nil, sort: [MembershipSortField] = [], limit: Int? = 100, page: PubNubHashedPage? = Page(), custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
Parameter Type Required Defaults Description channel
String Yes Unique Channel identifier. uuids
[PubNubMembershipMetadata] Yes Array of PubNubMembershipMetadata
with thePubNubUUIDMetadata
oruuidMetadataId
providedinclude
MemberInclude Optional MemberInclude()
Whether to include the custom field in the fetch response filter
String? Optional nil
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here sort
[MembershipSortField] Optional []
List of properties to sort response objects. The following properties are valid for sorting: .object(.id)
,.object(.name)
,.object(.updated)
, and.updated
.limit
Int? Optional 100 The number of objects to retrieve at a time page
PubNubHashedPage? Optional PubNub.Page()
The paging object used for pagination custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success A
Tuple
containing anArray
ofPubNubMembershipMetadata
, and the next paginationPubNubHashedPage
(if one exists).public protocol PubNubMembershipMetadata { /// The unique identifier of the associated UUID var uuidMetadataId: String { get } /// The unique identifier of the associated Channel var channelMetadataId: String { get } /// The associated UUID metadata var uuid: PubNubUUIDMetadata? { get set } /// The associated Channel metadata var channel: PubNubChannelMetadata? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
public protocol PubNubHashedPage { /// The hash value representing the next set of data var start: String? { get } /// The hash value representing the previous set of data var end: String? { get } /// The total count of all objects withing range var totalCount: Int? { get } }
Failure An
Error
describing the failure.
Basic Usage
let newMembership = PubNubMembershipMetadataBase(
uuidMetadataId: "my_user", channelMetadataId: "my_channel"
)
pubnub.setMemberships(
channel: newMembership.channelMetadataId,
uuids: [newMembership]
) { result in
switch result {
case let .success(response):
print("The channel memberships for the uuid \(response.memberships)")
if let nextPage = response.next {
print("The next page used for pagination: \(nextPage)")
}
case let .failure(error):
print("Update Memberships request failed with error: \(error.localized### Description)")
}
}
Remove Channel Members
Description
Remove members from a Channel.
Method(s)
To Remove Channel Members
you can use the following method(s) in the Swift SDK:
removeMembers( channel metadataId: String, uuids members: [PubNubMembershipMetadata], include: MemberInclude = MemberInclude(), filter: String? = nil, sort: [MembershipSortField] = [], limit: Int? = 100, page: PubNubHashedPage? = Page(), custom requestConfig: RequestConfiguration = RequestConfiguration(), completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
Parameter Type Required Defaults Description channel
String Yes Unique Channel identifier. uuids
[PubNubMembershipMetadata] Yes Array of PubNubMembershipMetadata
with thePubNubUUIDMetadata
oruuidMetadataId
providedinclude
MemberInclude Optional MemberInclude()
Whether to include the custom field in the fetch response filter
String? Optional nil
Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here sort
[MembershipSortField] Optional []
List of properties to sort response objects. The following properties are valid for sorting: .object(.id)
,.object(.name)
,.object(.updated)
, and.updated
.limit
Int? Optional 100 The number of objects to retrieve at a time page
PubNubHashedPage? Optional PubNub.Page()
The paging object used for pagination custom
RequestConfiguration Optional RequestConfiguration()
An object that allows for per-request customization of PubNub Configuration or Network Session completion
((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)? Optional nil
The async Result
of the method call
Completion Handler Result
Success A
Tuple
containing anArray
ofPubNubMembershipMetadata
, and the next paginationPubNubHashedPage
(if one exists).public protocol PubNubMembershipMetadata { /// The unique identifier of the associated UUID var uuidMetadataId: String { get } /// The unique identifier of the associated Channel var channelMetadataId: String { get } /// The associated UUID metadata var uuid: PubNubUUIDMetadata? { get set } /// The associated Channel metadata var channel: PubNubChannelMetadata? { get set } /// The last updated timestamp for the object var updated: Date? { get set } /// The caching identifier for the object var eTag: String? { get set } /// All custom fields set on the object var custom: [String: JSONCodableScalar]? { get set } }
public protocol PubNubHashedPage { /// The hash value representing the next set of data var start: String? { get } /// The hash value representing the previous set of data var end: String? { get } /// The total count of all objects withing range var totalCount: Int? { get } }
Failure An
Error
describing the failure.
Basic Usage
let oldMembership = PubNubMembershipMetadataBase(
uuidMetadataId: "my_user", channelMetadataId: "my_channel"
)
pubnub.removeMembers(
channel: oldMembership.channelMetadataId,
uuids: [oldMembership]
) { result in
switch result {
case let .success(response):
print("The channel memberships for the uuid \(response.memberships)")
if let nextPage = response.next {
print("The next page used for pagination: \(nextPage)")
}
case let .failure(error):
print("Update Memberships request failed with error: \(error.localized### Description)")
}
}
Objects Filtering Language Definition
The filtering language for Objects is similar to the stream filtering language.
Note the following:
Date/time properties, such as
updated
, must be compared to valid date/time strings formatted according to ISO 8601.The LIKE operator supports wildcards denoted by the
*
character. A wildcard matches any sequence of arbitrary Unicode characters, including the empty sequence. The literal asterisk is matched when escaped using the backslash (\
) character.Values used with LIKE must be properly encoded just like any other string value. Thus, in order to escape an asterisk, the raw value must contain
\\*
.The entire expression must be properly URL-encoded when used in the query string.
Custom property filtering
You can't filter by custom properties.
<expression> ::= <and_expression> ( "||" <and_expression> )*
<and_expression> ::= <binary_condition> ( "&&" <binary_condition> )*
<binary_condition> ::= "!" <binary_condition> | "(" <expression> ")" | <relational_condition>
<relational_condition> ::= <property_path> <relational_operator> <value>
<property_path> ::= <property_name> ( "." <property_name> )*
<property_name> ::= <identifier> | "[" <string> "]"
<value> ::= <string> | <number> | "true" | "false" | "null"
Tokens
<identifier> ::= <letter> | "$" | "_" ( <letter> | "$" | "_" | <digit> )*
<relational_operator> ::= "==" | "!=" | "<=" | ">=" | "<" | ">" | "LIKE"
<string> ::= <double_quote> ( "\" <double_quote> | "\" <special_char>
| "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
| <unicode_char> - <double_quote> - "\" )* <double_quote>
| "'" ( "\" "'" | "\" <special_char>
| "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
| <unicode_char> - "'" - "\" )* "'"
<number> ::= ( "+" | "-" )? ( <digit> )* ( "." )? <digit> ( <digit> )*
( "e" | "E" ( "+" | "-" )? <digit> ( <digit> )* )?
<letter> ::= Unicode Letter (category; any kind of letter from any language)
<digit> ::= "0" .. "9"
<hex_digit> ::= <digit> | "A" .. "F"
<double_quote> ::= the " character
<unicode_char> ::= any character in the Unicode range from U+0020 to U+10FFFF inclusive
<special_char> ::= "\" | "/" | "b" | "f" | "n" | "r" | "t"
Sample object filtering operations
The following date/time comparison returns results that were modified on or after August 31st, 2019 (UTC):
updated >= "2019-08-31T00:00:00Z"
The following wildcard expression returns results whose name starts with the letter X:
name LIKE 'X*'
The following escaped wildcard expression returns results whose name contains an asterisk:
name LIKE '*\\**'