Astra.Rest (astra v0.5.0)

Astra.Rest provides functions to access the public methods of the REST interface for databases hosed on https://astra.datastax.com.

Astra's REST interface is implemented using the stargate project, https://stargate.io. Swagger docs for this interface are available here https://docs.astra.datastax.com/reference#keyspaces-2.

If required, raw access to the Astra REST api can be obtained through the Astra.Rest.Http module.

Link to this section Summary

Functions

Add a row. All fields in the row are optional except for fields defined in the PRIMARY KEY of the table definition.

get_row retrieves one or more rows based on the keyspace, table and primary_key. Primary keys that span multiple fields should be delimeted with a \ ex. "123\tuesday".

Similar to Astra.Rest.add_row/3, the key needs to be provided explicity.

Search for rows in a table. The following operators are available for the query: $eq, $lt, $lte, $gt, $gte, $ne, and $exists.

Update part of a row, only fields provided in the entity will be updated.

Link to this section Functions

Link to this function

add_row(keyspace, table, entity)

Specs

add_row(String, String, Map) :: {Atom, Map}

Add a row. All fields in the row are optional except for fields defined in the PRIMARY KEY of the table definition.

Parameters

  • keyspace: the keyspace containing the target table
  • table: the table containing the entity we are retrieving
  • entity: a Map of the attributes of the row we are adding

ex.

    %{
      id: "83b8d85d-bd33-4650-8b9d-b43354187114",
      name: "test row"
    }

Examples

  > new_row = %{id: "83b8d85d-bd33-4650-8b9d-b43354187114", name: "test row"}
  > Astra.Rest.add_row("test", "thing", new_row)
  {:ok, %{id: "83b8d85d-bd33-4650-8b9d-b43354187114"}}
Link to this function

delete_row(keyspace, table, key)

Specs

delete_row(String, String, String) :: {Atom, []}

Remove a row.

Parameters

  • keyspace: the keyspace containing the target table
  • table: the table containing the entity we are retrieving
  • key: a primary key, if it contains multiple fields they should be seperated with \

Examples

  > new_row = %{id: "83b8d85d-bd33-4650-8b9d-b43354187114", name: "test row"}
  > Astra.Rest.delete_row("test", "thing", "83b8d85d-bd33-4650-8b9d-b43354187114")
  {:ok, []]}
Link to this function

get_row(keyspace, table, primary_key)

Specs

get_row(String, String, String) :: {Atom, [Map]}

get_row retrieves one or more rows based on the keyspace, table and primary_key. Primary keys that span multiple fields should be delimeted with a \ ex. "123\tuesday".

Examples

> Astra.Rest.get_row("test", "thing", "83b8d85d-bd33-4650-8b9d-b43354187114") 
{:ok, [%{id: "83b8d85d-bd33-4650-8b9d-b43354187114", name: "test row"}]}
Link to this function

replace_row(keyspace, table, key, entity)

Specs

replace_row(String, String, String, Map) :: {Atom, Map}

Similar to Astra.Rest.add_row/3, the key needs to be provided explicity.

Parameters

  • keyspace: the keyspace containing the target table
  • table: the table containing the entity we are retrieving
  • key: a primary key, if it contains multiple fields they should be seperated with \
  • entity: a Map of the attributes of the row we are adding

ex.

    %{
      id: "83b8d85d-bd33-4650-8b9d-b43354187114",
      name: "test row"
    }

Examples

  > new_row = %{name: "test row"}
  > Astra.Rest.replace_row("test", "thing", "83b8d85d-bd33-4650-8b9d-b43354187115", new_row)
  {:ok, %{name: "test row"}}
  > Astra.Rest.get_row("test", "thing", "83b8d85d-bd33-4650-8b9d-b43354187115")
  {:ok, [%{id: "83b8d85d-bd33-4650-8b9d-b43354187115", name: "test row"}]}
Link to this function

search_table(keyspace, table, query)

Specs

search_table(String, String, Map) :: {Atom, []}

Search for rows in a table. The following operators are available for the query: $eq, $lt, $lte, $gt, $gte, $ne, and $exists.

Please note that some restrictions exist for searches:

  1. Search cannot be on a PRIMARY KEY field, unless a composite primary key is being used.
  2. Search fields will require some form of secondary index. SAI is usually the best choice https://docs.astra.datastax.com/docs/using-storage-attached-indexing-sai

Example of creating an SAI index on a table:

CREATE TABLE thing (
  id text PRIMARY KEY,
  name text
) 

CREATE CUSTOM INDEX things_name_idx 
  ON thing (name) USING 'StorageAttachedIndex' 
  WITH OPTIONS = {'normalize': 'true', 'case_sensitive': 'false'};

Parameters

  • keyspace: the keyspace containing the target table
  • table: the table containing the entity we are retrieving
  • query: the search query for the table. ex. %{name: %{"$in": ["red", "blue"]}}

    Examples

  > Astra.Rest.search_table("test", "thing", %{name: %{"$eq": "test row"}}) 
Link to this function

update_partial_row(keyspace, table, key, changes)

Specs

update_partial_row(String, String, String, Map) :: {Atom, Map}

Update part of a row, only fields provided in the entity will be updated.

Parameters

  • keyspace: the keyspace containing the target table
  • table: the table containing the entity we are retrieving
  • key: a primary key, if it contains multiple fields they should be seperated with \
  • entity: a Map of the attributes of the row we are adding

ex.

    %{
      id: "83b8d85d-bd33-4650-8b9d-b43354187114",
      name: "test row"
    }

Examples

  > new_row = %{id: "83b8d85d-bd33-4650-8b9d-b43354187114", name: "test row"}
  > Astra.Rest.add_row("test", "thing", new_row)
  {:ok, %{id: "83b8d85d-bd33-4650-8b9d-b43354187114"}}