Save and Access Items

Stately’s API offers a small handful of simple methods for creating and accessing your Items.

Prerequisites

1. Create a Stately account and a Store
2. Install an SDK for your language
3. Define a schema and generate language-specific code
4. Set up a client to talk to your Store

Saving Items with Put

Using the simple User item type from Define a Schema, we can quickly create new Users and Put them into our Store:

Go

package main

import (
  "context"
  "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 CreateUser(
  ctx context.Context,
  client stately.Client,
) (uuid.UUID, error) {
  user, err := client.Put(ctx, &schema.User{
    // No Id is needed, it will be auto-generated by Stately
    DisplayName:   "Stately Support",
    Email:         "[email protected]",
    LastLoginDate: time.Now(),
    NumLogins:     1,
  })
  if err != nil {
    return uuid.Nil, err
  }
  userID := user.(*schema.User).Id
  return userID, nil
}

Ruby

def create_user(client)
  item = client.put(StatelyDB::Types::User.new(
    # No id is needed, it will be auto-generated by Stately
    displayName:   "Stately Support",
    email:         "[email protected]",
    lastLoginDate: Time::now.to_i,
    numLogins:     1,
  ))

  return item.id
end

Python

from __future__ import annotations

from typing import TYPE_CHECKING

from statelydb import key_path

from .schema import Client, User


async def create_user(client: Client) -> None:
    item = await client.put(
        User(
            # No id is needed, it will be auto-generated by Stately
            displayName="Stately Support",
            email="[email protected]",
            lastLoginDate=time.time(),
            numLogins=1,
        )
    )
    return item.id

TypeScript

import { keyPath } from "@stately-cloud/client";
import {
  createClient,
  DatabaseClient,
  Movie,
  User,
} from "./schema/index.js";

async function createUser(client: DatabaseClient) {
  const item = await client.put(
    client.create("User", {
      // No id is needed, it will be auto-generated by Stately
      displayName: "Stately Support",
      email: "[email protected]",
      lastLoginDate: BigInt(Date.now() / 1000),
      numLogins: 1n,
    }),
  );

  return item.id;
}

Our generated code contains typed objects for the User item type, so we can directly create that object and then call client.put to save it. The returned value is the version of the item that was saved in the database, including fields that StatelyDB filled in, such as the User’s new id.

Retrieving Items with Get

We can Get the user back using its key path:

Go

package main

import (
  "context"
  "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 GetUser(
  ctx context.Context,
  client stately.Client,
  userID []byte,
) (*schema.User, error) {
  item, err := client.Get(
    ctx,
    "/usr-"+stately.ToKeyID(userID),
  )
  if err != nil {
    return nil, err
  }
  return item.(*schema.User), nil
}

Ruby

def get_user(client, user_id)
  user = client.get(StatelyDB::KeyPath.with('usr', user_id))
  return user
end

Python

from __future__ import annotations

from typing import TYPE_CHECKING

from statelydb import key_path

from .schema import Client, User


async def get_user(client: Client, user_id: UUID) -> User | None:
    return await client.get(User, key_path("/usr-{id}", id=user_id))

TypeScript

import { keyPath } from "@stately-cloud/client";
import {
  createClient,
  DatabaseClient,
  Movie,
  User,
} from "./schema/index.js";

async function getUser(
  client: DatabaseClient,
  userID: Uint8Array,
): Promise<User | undefined> {
  const user = await client.get("User", keyPath`/usr-${userID}`);
  return user;
}

More APIs

Put and Get are the two most basic APIs - see Delete, List, and Transactions for more things you can do.