API reference for Momento Storage

Control APIs

These API methods are used to manage and control stores.

Create store

Creates a store with the provided name

Attributes:

Name	Type	Description
storeName	String	Name of the store to be created.

JavaScript

const result = await storageClient.createStore(storeName);
switch (result.type) {
  case CreateStoreResponse.AlreadyExists:
    console.log(`Store '${storeName}' already exists`);
    break;
  case CreateStoreResponse.Success:
    console.log(`Store '${storeName}' created`);
    break;
  case CreateStoreResponse.Error:
    throw new Error(
      `An error occurred while attempting to create store '${storeName}': ${result.errorCode()}: ${result.toString()}`
    );
}

Java

final CreateStoreResponse response = storageClient.createStore("test-store").join();
if (response instanceof CreateStoreResponse.Success) {
  System.out.println("Store 'test-store' created");
} else if (response instanceof CreateStoreResponse.Error error) {
  if (error.getCause() instanceof StoreAlreadyExistsException) {
    System.out.println("Store 'test-store' already exists");
  } else {
    throw new RuntimeException(
        "An error occurred while attempting to create store 'test-store': "
            + error.getErrorCode(),
        error);
  }
}

Go

resp, err := storageClient.CreateStore(ctx, &momento.CreateStoreRequest{
	StoreName: storeName,
})
if err != nil {
	panic(err)
}

switch resp.(type) {
case *responses.CreateStoreSuccess:
	fmt.Printf("Successfully created store %s\n", storeName)
case *responses.CreateStoreAlreadyExists:
	fmt.Printf("Store %s already exists\n", storeName)
}

PHP

$create_store_response = $storage_client->createStore($store_name);
if ($create_store_response->asSuccess()) {
    print("Store $store_name created\n");
} elseif ($create_store_response->asAlreadyExists()) {
    print("Store $store_name already exists\n");
} elseif ($err = $create_store_response->asError()) {
    print("An error occurred while attempting to create $store_name: {$err->errorCode()} - {$err->message()}\n");
}

Rust

  let response = storage_client.create_store(store_name).await?;
  match response {
      momento::storage::CreateStoreResponse::Created => println!("Store {} created", store_name),
      momento::storage::CreateStoreResponse::AlreadyExists => println!("Store {} already exists", store_name),
  }

Delete store

Deletes a store

Attributes:

Name	Type	Description
storeName	String	Name of the store to be deleted.

JavaScript

const result = await storageClient.deleteStore(storeName);
switch (result.type) {
  case DeleteStoreResponse.Success:
    console.log(`Store '${storeName}' deleted`);
    break;
  case DeleteStoreResponse.Error:
    throw new Error(
      `An error occurred while attempting to delete store '${storeName}': ${result.errorCode()}: ${result.toString()}`
    );
}

Java

final DeleteStoreResponse response = storageClient.deleteStore("test-store").join();
if (response instanceof DeleteStoreResponse.Success) {
  System.out.println("Store 'test-store' deleted");
} else if (response instanceof DeleteStoreResponse.Error error) {
  throw new RuntimeException(
      "An error occurred while attempting to delete store 'test-store': "
          + error.getErrorCode(),
      error);
}

Go

_, err := storageClient.DeleteStore(ctx, &momento.DeleteStoreRequest{
	StoreName: storeName,
})
if err != nil {
	panic(err)
}

PHP

$delete_store_response = $storage_client->deleteStore($store_name);
if ($err = $delete_store_response->asError()) {
    print("An error occurred while attempting to delete $store_name: {$err->errorCode()} - {$err->message()}\n");
} else {
    print("Store $store_name deleted\n");
}

Rust

  storage_client.delete_store(store_name).await?;
  println!("Store {} deleted", store_name);

List stores

Lists all stores

JavaScript

const result = await storageClient.listStores();
switch (result.type) {
  case ListStoresResponse.Success:
    console.log(
      `Stores:\n${result
        .stores()
        .map(c => c.getName())
        .join('\n')}\n\n`
    );
    break;
  case ListStoresResponse.Error:
    throw new Error(`An error occurred while attempting to list stores: ${result.errorCode()}: ${result.toString()}`);
}

Java

final ListStoresResponse response = storageClient.listStores().join();
if (response instanceof ListStoresResponse.Success success) {
  final String stores =
      success.getStores().stream().map(StoreInfo::getName).collect(Collectors.joining("\n"));
  System.out.println("Stores:\n" + stores);
} else if (response instanceof ListStoresResponse.Error error) {
  throw new RuntimeException(
      "An error occurred while attempting to list stores: " + error.getErrorCode(), error);
}

Go

resp, err := storageClient.ListStores(ctx, &momento.ListStoresRequest{})
if err != nil {
	panic(err)
}

switch r := resp.(type) {
case *responses.ListStoresSuccess:
	log.Printf("Found stores:\n")
	for _, store := range r.Stores() {
		log.Printf("\tStore name: %s\n", store.Name())
	}
}

PHP

$list_stores_response = $storage_client->listStores();
if ($listSuccess = $list_stores_response->asSuccess()) {
    print("Found stores:\n");
    foreach ($listSuccess->stores() as $store) {
        $store_name = $store->name();
        print("- $store_name\n");
    }
} elseif ($err = $list_stores_response->asError()) {
    print("An error occurred while attempting to list stores: {$err->errorCode()} - {$err->message()}\n");
}

Rust

  let response = storage_client.list_stores().await?;
  println!("Stores: {:#?}", response.stores);

Data APIs

These API methods are used to directly interact with data in a store.

Put

Puts a value into the store. If a value for this key is already present it will be replaced by the new value.

Name	Type	Description
storeName	String	Name of the store.
key	String	The key under which the value is to be added.
value	String / Bytes / Integer / Double	The value to be stored.

JavaScript

// to store a string value:
const result = await storageClient.putString(storeName, 'test-key', 'test-value');
switch (result.type) {
  case StoragePutResponse.Success:
    console.log("Key 'test-key' stored successfully");
    break;
  case StoragePutResponse.Error:
    throw new Error(
      `An error occurred while attempting to store key 'test-key' in store '${storeName}': ${result.errorCode()}: ${result.toString()}`
    );
}

// Momento storage also supports these other data types:
await storageClient.putInt(storeName, 'test-key', 42);
await storageClient.putDouble(storeName, 'test-key', 3.14);
await storageClient.putBytes(storeName, 'test-key', Buffer.from('test-value'));

Java

// this example illustrates how to store a String value
final PutResponse response = storageClient.put("test-store", "test-key", "test-value").join();
if (response instanceof PutResponse.Success) {
  System.out.println("Key 'test-key' stored successfully");
} else if (response instanceof PutResponse.Error error) {
  throw new RuntimeException(
      "An error occurred while attempting to store key 'test-key' in store 'test-store': "
          + error.getErrorCode(),
      error);
}

// Momento Storage also supports storing values of type byte[], long, and double:
byte[] bytesValue = "test-byte-array-value".getBytes(StandardCharsets.UTF_8);
storageClient.put("test-store", "test-byte-array-key", bytesValue).join();
storageClient.put("test-store", "test-integer-key", 42L).join();
storageClient.put("test-store", "test-double-key", 42.0).join();

Go

_, err := storageClient.Put(ctx, &momento.StoragePutRequest{
	StoreName: storeName,
	Key:       "key",
	Value:     storageTypes.String("my-value"),
})
if err != nil {
	panic(err)
}

// Momento storage also supports these other data types:
storageClient.Put(ctx, &momento.StoragePutRequest{
	StoreName: storeName,
	Key:       "key",
	Value:     storageTypes.Int(42),
})
storageClient.Put(ctx, &momento.StoragePutRequest{
	StoreName: storeName,
	Key:       "key",
	Value:     storageTypes.Float(3.14),
})
storageClient.Put(ctx, &momento.StoragePutRequest{
	StoreName: storeName,
	Key:       "key",
	Value:     storageTypes.Bytes{0x01, 0x02, 0x03},
})

PHP

$put_response = $storage_client->putString($store_name, "test-key", "test-value");
if ($put_response->asSuccess()) {
    print("Key 'test-key' stored successfully\n");
} elseif ($err = $put_response->asError()) {
    print("An error occurred while attempting to store 'test-key': {$err->errorCode()} - {$err->message()}\n");
}

// Momento storage also supports int, float, and bytes types.
// Because strings in PHP are a series of bytes, the putBytes method accepts a string as the value.
$put_response = $storage_client->putBytes($store_name, "test-key", "test-value");
$put_response = $storage_client->putInt($store_name, "test-key", 42);
$put_response = $storage_client->putFloat($store_name, "test-key", 3.14);

Rust

  storage_client.put(store_name, "key", "value").await?;
  println!("Put key and value in store {}", store_name);

Get

Get the value stored for the given key.

Name	Type	Description
storeName	String	Name of the store.
key	String	The key whose value is to be retrieved.

JavaScript

const getResponse = await storageClient.get(storeName, 'test-key');
// simplified style; assume the value was found, and that it was a string
console.log(`string hit: ${getResponse.value()!.string()!}`);

// if the value was an integer:
const integerGetResponse = await storageClient.get(storeName, 'test-integer-key');
console.log(`integer hit: ${integerGetResponse.value()!.int()!}`);

// pattern-matching style; safer for production code
switch (getResponse.type) {
  case StorageGetResponse.Found:
    // if you know the value is a string:
    console.log(`Retrieved value for key 'test-key': ${getResponse.value().string()!}`);
    break;
  case StorageGetResponse.NotFound:
    console.log(`Key 'test-key' was not found in store '${storeName}'`);
    break;
  case StorageGetResponse.Error:
    throw new Error(
      `An error occurred while attempting to get key 'test-key' from store '${storeName}': ${getResponse.errorCode()}: ${getResponse.toString()}`
    );
}

Java

final GetResponse response = storageClient.get("test-store", "test-key").join();

// simplified style to access the value, if you're confident the value exists and you know the
// type.
// The optionals in this chain will throw exceptions when you call `.get()` if the item did not
// exist in the store, or is another type besides a String
final String value = response.valueWhenFound().get().getString().get();

// Or, you can use pattern-matching for more production-safe code:
if (response instanceof GetResponse.Found found) {
  // if you know the value is a String:
  String stringValue =
      found
          .value()
          .getString()
          .orElseThrow(() -> new RuntimeException("Value was not a String!"));
  // if you don't know the type of the value:
  switch (found.value().getType()) {
    case STRING -> System.out.println("String value: " + found.value().getString().get());
    case BYTE_ARRAY -> System.out.println(
        "Byte array value: " + found.value().getByteArray().get());
    case LONG -> System.out.println("Long value: " + found.value().getLong().get());
    case DOUBLE -> System.out.println("Double value: " + found.value().getDouble().get());
  }
} else if (response instanceof GetResponse.NotFound) {
  System.out.println("Key 'test-key' was not found in store 'test-store'");
} else if (response instanceof GetResponse.Error error) {
  throw new RuntimeException(
      "An error occurred while attempting to get key 'test-key' from store 'test-store': "
          + error.getErrorCode(),
      error);
}

Go

getResp, err := storageClient.Get(ctx, &momento.StorageGetRequest{
	StoreName: storeName,
	Key:       "key",
})
if err != nil {
	panic(err)
}

// If the value was not found, the response's Value will be nil.
if getResp.Value() == nil {
	fmt.Println("Got nil")
}

// If you know the type you're expecting, you can assert it directly:
intVal, ok := getResp.Value().(storageTypes.Int)
if !ok {
	fmt.Printf("Not an integer, received type: %T\n", getResp.Value())
} else {
	fmt.Printf("Got the integer %d\n", intVal)
}

// Use switch if you don't know the type beforehand:
switch t := getResp.Value().(type) {
case storageTypes.String:
	fmt.Printf("Got the string %s\n", t)
case storageTypes.Bytes:
	fmt.Printf("Got the bytes %b\n", t)
case storageTypes.Float:
	fmt.Printf("Got the float %f\n", t)
case storageTypes.Int:
	fmt.Printf("Got the integer %d\n", t)
case nil:
	fmt.Println("Got nil")
}

PHP

$get_response = $storage_client->get($store_name, "test-key");
if ($found = $get_response->asFound()) {
    $value_type = $found->type();
    if ($value_type == StorageValueType::STRING) {
        print("Got string value: " . $found->valueString() . "\n");
    } elseif ($value_type == StorageValueType::INT) {
        print("Got integer value: " . $found->valueInt() . "\n");
    } elseif ($value_type == StorageValueType::FLOAT) {
        print("Got float value: " . $found->valueFloat() . "\n");
    } elseif ($value_type == StorageValueType::BYTES) {
        // This case is not expected in this example as PHP doesn't have a native byte type
        print("Got bytes value: " . $found->valueBytes() . "\n");
    }
    // You may also pull the value directly from the response without type checking
    print("Retrieved value for key 'test-key': {$get_response->value()}\n");
} elseif ($get_response->asNotFound()) {
    print("Key 'test-key' was not found in store $store_name\n");
} elseif ($err = $get_response->asError()) {
    print("An error occurred while attempting to get key 'test-key' from store $store_name: {$err->errorCode()} - {$err->message()}\n");
}

Rust

  let response = storage_client.get(store_name, "key").await?;
  match response {
      momento::storage::GetResponse::NotFound => println!("Key not found in {}", store_name),
      momento::storage::GetResponse::Found { value } => {
          // A Found response indicates the value was found in the store.

          // Use `match` to get the value if you don't know the type beforehand:
          match value.clone() {
              momento::storage::StorageValue::String(value) => println!("Got string value {}", value),
              momento::storage::StorageValue::Bytes(value) => println!("Got bytes value {:?}", value),
              momento::storage::StorageValue::Integer(value) => println!("Got integer value {}", value),
              momento::storage::StorageValue::Double(value) => println!("Got double value {}", value),
          }

          // If you know the type you're expecting, you can `try_into()` it directly:
          let found_value: String = value.try_into()?;
          println!("Got value {}", found_value);
      }
  }

Delete

Delete the value stored for the given key.

Name	Type	Description
storeName	String	Name of the store.
key	String	The key whose value is to be deleted.

JavaScript

const result = await storageClient.delete(storeName, 'test-key');
switch (result.type) {
  case StorageDeleteResponse.Success:
    console.log("Key 'test-key' deleted successfully");
    break;
  case StorageDeleteResponse.Error:
    throw new Error(
      `An error occurred while attempting to delete key 'test-key' from store '${storeName}': ${result.errorCode()}: ${result.toString()}`
    );
}

Java

final DeleteResponse response = storageClient.delete("test-store", "test-key").join();
if (response instanceof DeleteResponse.Success) {
  System.out.println("Key 'test-key' deleted successfully");
} else if (response instanceof DeleteResponse.Error error) {
  throw new RuntimeException(
      "An error occurred while attempting to delete key 'test-key' from store 'test-store': "
          + error.getErrorCode(),
      error);
}

Go

_, err := storageClient.Delete(ctx, &momento.StorageDeleteRequest{
	StoreName: storeName,
	Key:       "key",
})
if err != nil {
	panic(err)
}

PHP

$delete_response = $storage_client->delete($store_name, "test-key");
if ($delete_response->asSuccess()) {
    print("Key 'test-key' deleted successfully\n");
} elseif ($err = $delete_response->asError()) {
    print("An error occurred while attempting to delete key 'test-key' from store $store_name: {$err->errorCode()} - {$err->message()}\n");
}

Rust

  storage_client.delete(store_name, "key").await?;
  println!("Deleted key from store {}", store_name);

Current status of API support in SDKs

For the current status of API support in various SDK languages, see the language support page.