DataStax Astra DB uses the Stargate GraphQL API to easily modify and query yourtable data using GraphQL types, queries, and mutations.
The CQL-first approach directly translates CQL tables into GraphQL types, mutations, and queries.The GraphQL schema is automatically generated from the keyspace, tables, and columnsdefined, but no customization is allowed.A standard set of mutations and queries are produced for searching and modifying the table data.If you are familiar with Cassandra, you might prefer this approach.
To use Stargate with Astra DB you need to:
- Register for Astra DB.
- Create a database after you log into your Astra account.
- Generate an application token to use the GraphQL Playground and cURL.
- Run GraphQL Playground to deploy schema,and execute mutations and queries.
- Optional: cURL to run GraphQL queries from command-line.
- Optional: Postman collections if you wish to execute mutations and queries inPostman.
User-defined types (UDTs) are custom data types that a user can create and usein table definitions. They are entirely optional, but sometimes useful if youhave data that you would like to group together in a single column.UDTs must be added before you define or add a column using the data type ina table schema.
Prerequisites
- Get an application token.
- Create a keyspace using the DataStax Astra DB dashboard.
This example creates a UDT called address_type that includes a street, city,state, and zip code.
In order to use the GraphQL API, you must create schema that defines the tablesthat will store the data, in a keyspace that you have defined with the DataStax Astra DB UI.Tables consist of columns that have a defined data type. Multiple tables are containedin a keyspace, but a table cannot be contained in multiple keyspaces.
Prerequisites
- Get an application token.
- Create a keyspace using the DataStax Astra DB dashboard.
Use the application token you generatedto create schema in your keyspace using the GraphQL playground.
Creating a table
You can create a table using a mutation in /graphql-schema .In the following example, products is the table name.The table columns are name , description , price , and created .
+A special column, partitionKey , defines the outermost grouping of data, similar to a schema in a relational database.In this example, we'll use the name column to group our data.
In this example, create two tables by executing the following mutation, in eitherthe GraphQL playground, or by executing the cURL command in a terminal.The first table, book includes the table columns title and author .A special column or columns, partitionKeys , defines the outermost grouping of data,similar to a schema in a relational database.For book , the title column groups the data.Another special column or columns, clusteringKeys can sort the data within atable.For book , the author column sorts the data.
It is worth noting that one mutation is used to create two tables.Information about partition keys and clustering keys can be found in theCQL reference.
The second table, reader , also defines a column using the UDT that wascreated above.
Data types
Tables can be created with an option ifNotExists .They can also be created with collections (set, list, map), tuples, and UDTs.
IF NOT EXISTS option
A table can be created with an option ifNotExists that will only create thetable if it does not already exist:
One of these tables includes creating a column with the data type LIST , an orderedcollection of text values.
Collection (set, list, map) columns
Including a collection in a table has a couple of extra parts:
This example shows a map. A previous example shows a list.In the next example, a set will be used.
Adding columns to table schema
If you need to add more attributes to something you are storing in a table, youcan add one or more columns:
Checking that keyspaces and tables exist
To check if a keyspace, tables, or particular table columns exist, execute aGraphQL query:
For keyspaces and tables:
And for tables:
Because these queries are named, the GraphQL playground will allow you to selectwhich query to run. The first query will return information about the keyspace library and the tables within it. The second query will return just informationabout the tables in that keyspace.
Create an index
Prerequisites
- Get an application token.
- Create a keyspace using the DataStax Astra DB dashboard.
- Create a table.
Use the application token you generatedto create schema in your keyspace using the GraphQL playground.
Tables can contain partition keys and clustering keys, both of which define theprimary key. A table can also include non-primary keys.
If you wish to create a table query that uses anything other than the partition keyto define which row or rows are to be retrieved, a column index must be createdon each column in order to read the data.
Currently, those indexes can be created withCQLor GraphQL.
Use the application token you generatedto create schema in your keyspace using the GraphQL playground.
You can create an index using a mutation in /graphql-schema .In the following example, three indexes are created for the tables book and reader .The table columns for these indexes are created are author , birthdate , and email .
An index name can be defined, such as author_idx in this example.An additional option, indexType can be defined to use SAI indexes if desired.
Here is an additional example, which creates indexes that could be used in the REST API examples:
The CQL commands for creating these indexes is included here for reference.The cqlsh tool can be used to create the indexes if desired.
Prerequisites
- Get an application token.
- Create a keyspace using the DataStax Astra DB dashboard.
- Optional Creating UDTs.
- Creating a table.
- Optional Creating an index.
Dropping a type
You can delete a type. All tables that use the UDT must first be deleted.
Dropping a table
You can delete a table. All data will be deleted along with the table schema.
IF EXISTS option
You can delete a table after checking that it exists with the ifExists option.All data will be deleted along with the table schema.
Dropping columns from table schema
If you find an attribute is no longer required in a table, you can remove a column.All column data will be deleted along with the column schema.
Dropping an index from table schema
If you find an index is no longer required on a table column, or you need to change the index,you can remove it.All index data will be deleted along with the index schema.
Insert data in your tables using Astra DB's GraphQL API.
After creating a table inyour keyspace using GraphQL, you can add rows of data.
Prerequisites
Write data
Any of the created APIs can be used to interact with the GraphQL data, to writeor read data.
First, let's navigate to your new keyspace library inside the playground.Switch to the graphql tab in the GraphQL playground, and change the locationto https://$ASTRACLUSTERID-$ASTRA_REGION.apps.astra.datastax.com/api/graphql/library The main importance is changing the keyspace name, as the default is system .
First, let's add a couple of books to the book table:
Note that the keyword value is used twice in the mutation.The first use defines the value that the record is set to, for instance, the titleto Moby Dick and the author to Herman Melville.The second use defines the values that will be displayed after the successof the mutation, so that proper insertion can be verified.This same method is valid for updates and read queries.
Insertion options
Three insertion options are configurable during data insertion or updating:
Note that in Astra DB, the consistency levels ANY , ONE , or LOCAL_ONE cannot be used.The default is LOCAL_QUORUM .
An example insertion that sets the consistency level and TTL:
The serial consistency can also be set with serialConsistency in the options,if needed.
Insert collections (set, list, map)
Inserting a collection is simple. An example of inserting a list:
A map is slightly more complex:
Insert a tuple
Inserting a tuple involves inserting an object; note the use of item0 , item1 ,and so on, to insert the parts of the tuple
Insert a user-defined type (UDT)
Inserting a UDT requires taking careful note of the brackets used:
Retrieve data from your tables using Astra's GraphQL API.
After creating a table inyour keyspace using GraphQL and adding rows using GraphQL, you can retrieve data.
Prerequisites
- Getting an application token
- Creating a table in your keyspace using GraphQL
- Adding rows to your table
Read data
Let's check that the data was inserted.
Now let's search for a particular record using a WHERE clause. The primarykey of the table can be used in the WHERE clause, but non-primary key columnscannot be used.The following query, looking at the locationhttp://localhost:8080/graphql/library[http://localhost:8080/graphql/library]will get both the title and the author for the specified book WHEREtitle:"Moby Dick" :
To find multiple books, an addition to the WHERE clause is required, to denote thatthe list of titles desired is IN a group:
To display the contents of a UDT, notice the inclusion of addresses in the values displayed for this read query:
To display the contents of a map collection, notice the inclusion of earned in the values displayed for this read query:
Filter options for reading
The filters available are:
- eq (equal)
- notEq (not equal) - limited use in conditional statements
- gt (greater than)
- gte (greater than or equal to)
- lt (less than)
- lte (less than or equal to)
- in (within)
- contains (a map contains the specified value)
- containsKey (a map contains the specified key)
- containsEntry (a map contains the specified key:value pair)
Note that these can only be used with primary key columns, just like in Cassandra, unlessindexing is created.
The next examples will query the same table, badge , using a variety of filters to illustratethe versatility of such filters.The first example finds the record that has the partition key badge_type equal to Gold , andthe badge_id equal to 100 :
Now if we use a different operator gt with the same query, notice that the query will fail,because no badge_id greater than a value of 100 is found:
In order to use filters for any columns that are not part of the primary key, currentlyyou need to use CQL to create a secondary index using the CQL shell.The next three examples show the CQL creation of an index in order to query a columnthat is a map collection.
In this example, an index is created on the keys of the map earned , so the containsKey filter can be used to query in GraphQL.
Because the index now exists, it is also possible to just filter based on the map key itself:
In this next example, an index is created on the values of the map earned , so the contains filter can be used to query in GraphQL.
To make a complete set of filters, an index is created on the entries of the map earned , so the containsEntry filter can be used to query in GraphQL.
Limiting and paging results using query options
You can add options to the query to limit and add paging to the results.
Add the limit option to set the maximum number of results returned by the query.
The query results can be paged by using the pageSize and pageState options.
Set pageSize to the number of results returned at each step.The default value of pageSize is 100.
The pageState value is returned in the data of the last query.Pass the value of pageState from the previous query to retrieve the next pagein the results.
Update data in your tables using Astra's GraphQL API.
After creating a table in your keyspace and adding rows, you can update data.
Running an update mutation in Astra is an upsert. This means that if the row you are altering doesn't exist it will be created.
Prerequisites
- Getting an application token
- Creating a table in your keyspace using GraphQL
- Adding rows to your table
- Adding rows to your table
Using the column that we added earlier, the data for a book is updated with the ISBN value. If the call is successful, a message returns with the newly inserted row data:
It is also possible to update other types of data, such as a set:
Delete data in your tables using the DataStax Astra DB GraphQL API.
As needed, you can delete rows from tables.Use the delete object method to remove the rows in the table you created previously.
Prerequisites
- Getting an application token
- Creating a table in your keyspace using GraphQL
- Adding rows to your table
Delete data
After adding the book "Pride and Prejudice" with an `insertbook()`, you can deletethe book using `deletebook()` to illustrate deleting data.If the call is successful there won't be a return message.
Note the use of ifExists to validate that the book exists before deleting it.
Deletion options
Similar to the option ifExists , you can delete a book using consistency , serialConsistency , or ttl , similar to insertions: