The following diagram provides a simplified overview of the Models SDK:
An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using token authentication.
API keys and tokens have a set of capabilities assigned to them that specify which operations, such as
publish can be performed on which resources. To use the Models SDK, the API key requires the following capabilities
subscribefor the channels you intend to subscribe to.
historyif you intend to sync from historical messages.
Import the SDKs into your project:
In addition to the underlying Ably realtime client, you can provide a number of other
ClientOptions to configure the behavior of the Models SDK:
- is used to configure how the model state is synchronised via the sync function.
- is the limit used when querying for paginated history used to subscribe to changes from the correct point in the channel.
- is the message retention period configured on the channel. This is used to determine whether the model state can be brought up to date from message history rather than via a re-sync.
- defines a retry strategy to use if calling the sync function throws an error.
- used to configure the in-memory sliding-window buffer used for reordering and deduplication.
- is used to configure how optimistic events are applied.
- configures the log level used to control the verbosity of log output. One of
- captures a collection of named model instances used in your application and provides methods for creating new models.
The following is an example of setting
ClientOptions when instantiating the Models SDK:
A model is a single instance of a live, observable data model backed by your database. In this guide, we will create a simple model that tracks a list of comments on a post.
To create the model, use the
models.get() method on the client. If a model with the given name already exists, it will be returned.
To instantiate a Model you must provide a unique name. This identifies the model on the client, and is also the name of the channel used to subscribe to state updates from the backend.
The model also requires:
- Sync function to initialize the model’s state from the backend.
- Merge function to calculate the next version of the model state when change events are received from the backend.
Create a simple sync function that loads the post and its comments. The response should contain both:
Below is an example result from the sync function:
The Models SDK will infer the type of the model state from the type of the data payload returned by the sync function:
The sync endpoint on the backend returns the post data as well as a
sequenceID which defines the point in the stream of change events that corresponds to this version of the data. You can obtain the
sequenceID by reading the largest
sequenceID from the outbox table in the same transaction that queries the post data.
Create a simple merge function which defines how to calculate the next version of the model state when a change event is received from the backend. In this case, you will append the new comment to the list when an
addComment event is received:
Whenever new comments are added to the post, the model will be updated in realtime.
The following function will add a new comment using a backend endpoint:
On the backend, the endpoint inserts the new comment in the database and transactionally writes an
addComment change event with the provided
mutationID to the outbox table. This change event record is then broadcast to other clients subscribed to this model via the Database Connector. The following example demonstrates this:
Use optimistic updates to instantly update the model with the new comment data without waiting for confirmation from the backend: