Skip to content
StatelyDB

Listing Items

The List family of APIs are one of the most useful APIs in StatelyDB. While APIs like Put, Get, and Delete allow you to operate on individual Items by their full key path, List lets you fetch multiple Items from the same Group in one go (i.e. Items that share the same Group Key). This can be useful for fetching collections of Items such as a customer’s order history, or a list of messages in a conversation. It’s especially useful for implementing features like infinite scrolling lists, where you want to keep fetching more Items as the user scrolls down.

Beginning a Paginated List

Section titled “Beginning a Paginated List”

You start a list by calling BeginList with a key path prefix and an optional limit to get an initial result set. StatelyDB will return all the Items whose key paths have the given prefix.

Your initial result set might not contain all the Items under that prefix, if you set a page size limit. This initial result set is your first “page” of data - imagine it as the first several screens full of emails in your email app.

For this example we’ll use the schema defined in Example: Movies Schema, which defines these key paths (among others):

Item TypeKey Path Template
Movie/movie-:id
Character/movie-:movieId/role-:role/name-:name

Note how both Movie and Character share the same /movie-:id prefix.

17 collapsed lines
package main


import (
  "context"
  "fmt"
  "os"
  "slices"
  "strconv"
  "time"


  "github.com/google/uuid"


  "github.com/StatelyCloud/go-sdk/stately"
  // This is the code you generated from schema
  "github.com/StatelyCloud/stately/go-sdk-sample/schema"
)


func sampleList(
  ctx context.Context,
  client stately.Client,
  movieID uuid.UUID,
) (*stately.ListToken, error) {
  iter, err := client.BeginList(
    ctx,
    // This key path is a prefix of BOTH Movie and Character.
    "/movie-"+stately.ToKeyID(movieID[:]),
    stately.ListOptions{Limit: 10},
  )
  if err != nil {
    return nil, err
  }


  for iter.Next() {
    item := iter.Value()
    switch v := item.(type) {
    case *schema.Movie:
      fmt.Printf("Movie Title: %s\n", v.GetTitle())
    case *schema.Character:
      fmt.Printf("Character Name: %s\n", v.GetName())
    }
  }
  // When we've exhausted the iterator, we'll get a token that we
  // can use to fetch the next page of items.
  return iter.Token()
}

Using the List Token to Continue

Section titled “Using the List Token to Continue”

The result from BeginList includes a token which you can save for later, or use right away. Only the tokenData part of the token needs to be saved. There is also a canContinue property which indicates whether there are more pages still available, and canSync which indicates whether SyncList is supported for this list.

You can pass the token to ContinueList, which lets you fetch more results for your result set, continuing from where you left off. For example, you might call ContinueList to get the next few screens of emails when the user scrolls down in their inbox. Or, you could call it in the background to eventually pull the entire result set into a local database. All you need is the token—the original arguments to BeginList are saved with it.

The token keeps track of the state of the result set, and ContinueList allows you to expand the window of results that you have retrieved. Every time you call ContinueList, you’ll get a new token back, and you can use that token for the next ContinueList or SyncList call, and so on. This is also known as pagination, and it allows you to quickly show results to your users without having to get all the data at once, while still having the ability to grab the next results consistently.

For many applications, you’ll only need to call BeginList once, to set up the initial token, and from then on they’ll call ContinueList (as a user scrolls through results) or SyncList (whenever the user opens or focuses the application, to check for new and updated items).

In this example we’ve passed the token from the first example back into ContinueList to keep getting more Items:

17 collapsed lines
package main


import (
  "context"
  "fmt"
  "os"
  "slices"
  "strconv"
  "time"


  "github.com/google/uuid"


  "github.com/StatelyCloud/go-sdk/stately"
  // This is the code you generated from schema
  "github.com/StatelyCloud/stately/go-sdk-sample/schema"
)


func sampleContinueList(
  ctx context.Context,
  client stately.Client,
  token *stately.ListToken,
) (*stately.ListToken, error) {
  iter, err := client.ContinueList(ctx, token.Data)
  if err != nil {
    return nil, err
  }
  for iter.Next() {
    item := iter.Value()
    switch v := item.(type) {
    case *schema.Character:
      fmt.Printf("Character Name: %s\n", v.GetName())
    case *schema.Movie:
      fmt.Printf("Movie Title: %s\n", v.GetTitle())
    }
  }
  // You could save the token to call ContinueList later.
  return iter.Token()
}

Sort Direction

Section titled “Sort Direction”

By default, the items returned in a List are sorted by their key paths, in ascending order. Namespaces, string IDs, and byte IDs are sorted lexicographically, while number IDs are sorted numerically. For example:

  • /customer-1234
  • /customer-1234/order-9
  • /customer-1234/order-10
  • /customer-1234/order-10/li-abc
  • /customer-1234/order-10/li-bcd

You can specify a SortDirection option to reverse this order (from the default of Ascending to Descending).

Listing All Groups

Section titled “Listing All Groups”

If you have root item type, this can be achieved using the Scan operation to list all Items of the group type.

Listing Across Client Upgrades

Section titled “Listing Across Client Upgrades”

The list token you get from BeginList is specific to the schema version your client was built with. If you save that token, and then upgrade your client to another schema version, ContinueList will return a SchemaVersionMismatch error, since there’s no guarantee that the items you had cached are compatible with the new schema version. In this case you should discard the list token and start a new BeginList call.