GraphQL API

Astra uses the Stargate GraphQL API to easily modify and query your table data using GraphQL types, queries, and mutations.

For every table in your keyspace, a series of GraphQL objects are generated, along with queries and mutations for searching and modifying the table data.

For more information about the GraphQL API, see the blog post on the GraphQL API.

If you haven’t already, create a database using DataStax Astra.

We’ll show you you how to:

About the GraphQL API endpoints

There are two Astra GraphQL API endpoints, one for creating schema and the other for querying a keyspace. The URLS are:

Each request must have a valid application token and a unique id.

Generating UUIDs Consider using a tool like this online UUID generator to quickly create a random UUID to pass with your requests if you are submitting the queries manually using a tool like cURL.

Naming conventions for GraphQL

The GraphQL API uses specific naming conventions to preserve capitalization and special characters. Note that if typical GraphQL naming conventions are used, such as camelCase, that the underlying Cassandra storage tables will use double quoting to preserve the capitalization. If a naming conflict occurs, an error results that the table already exists.

Table 1. GraphQL naming convention
GraphQL table name CQL table name GraphQL mutation format

foo

foo

insertfoo

Foo

"Foo"

insertFoo

foo_bar

foo_bar

insertfoo_bar

FooBar

"FooBar"

insertFooBar

Hellox21_

"Hello!"

insertHellox21_

Mapping Astra tables to GraphQL fields and types

The Astra GraphQL API generates fields and types for each table in your database. For example, for an Astra table named book the following fields and types are generated.

schema {
  query: Query
  mutation: Mutation
}

type Query {
  book(value: bookInput, filter: bookFilterInput, orderBy: [bookOrder], options: QueryOptions): bookResult
  bookFilter(filter: bookFilterInput!, orderBy: [bookOrder], options: QueryOptions): bookResult
}

type Mutation {
  insertbook(value: bookInput!, ifNotExists: Boolean, options: UpdateOptions): bookMutationResult
  updatebook(value: bookInput!, ifExists: Boolean, ifCondition: bookFilterInput, options: UpdateOptions): bookMutationResult
  deletebook(value: bookInput!, ifExists: Boolean, ifCondition: bookFilterInput, options: UpdateOptions): bookMutationResult
}

Generated query types

The following query types are generated:

  • book(): Query book values by equality. If no value argument is provided, then the first hundred (default pagesize) values are returned.

  • bookFilter: Query book values by filtering the result with additional operators. For example gt (greater than), lt (less than), in (in a list of values). The book() equality style query is preferable if your queries don’t require non-equality operators.

Generated mutation types

The following mutations are generated:

Several mutations are created that you can use to insert, update, or delete books. Some important facts about these mutations are:

  • insertbook() is an upsert operation if a book with the same information exist, unless the ifNotExists is set to true.

  • updatebook() is also an upsert operation, and will create a new book if it doesn’t exist, unless ifNotExists is set to true.

  • deletebook() will delete a book.

  • Using the ifNotExists or ifCondition options affects the performance of operations because of the compare-and-set execution path in Cassandra. Under the hood these operations are using a feature in Cassandra called lightweight transactions (LWTs).

As more tables are added to your keyspace, additional fields are added to the query and mutation types to handle queries and mutations for the new tables.

Using the GraphQL Playground

The easiest way to get started with GraphQL uses the built-in GraphQL playground. In Astra, go to the Connect tab for your database, choose GraphQL under the Connect using an API and you’ll see instructions for accessing the playground. The GraphQL playground launches the url https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/playground in your browser.

Add your application token to the HTTP HEADERS section at the lower lefthand corner of the GraphQL Playground window:

{"x-cassandra-token":"$AUTH_TOKEN"}

Once in the playground, you can create new schema and interact with the GraphQL APIs. The server paths are structured to provide access to creating and querying schema, as well as querying and modifying Cassandra data:

  • /graphql-schema

    • An API for exploring and creating schema, or Data Definition Language (DDL). For example, Astra has queries to create, modify, or drop tables, such as createTable, or dropTable.

  • /graphql/<keyspace>

    • An API for querying and modifying your tables using GraphQL fields.

Using Postman

If you prefer, you can use Postman as a client interface for exploring the GraphQL API (download here). We’ve provided a Stargate GraphQL API Postman Astra Collection that you can import in Postman to play with the examples shown in this walkthrough.

We’ll start the playground with /graphql-schema to create some schema.