DataStax Astra Developer Hub

Welcome to the DataStax Astra Developer Hub. You'll find comprehensive guides and documentation to help you start working with DataStax Astra as quickly as possible. Use the included APIs to create, modify, and terminate databases, and interact with the databases you create. Let's do it!

Astra Docs      API Reference      CQL for Astra

Using the Astra GraphQL API

Astra has a GraphQL API that allows you to modify and query your table data.

The DataStax Astra GraphQL API allows you to easily interact with your data using GraphQL types, queries, and mutations. For every tabletable - Stores data based on a primary key, which consists of a partition key and optional clustering columns. A partition key defines the node on which the data is stored, and divides data into logical groups. Define partition keys that evenly distribute the data and also satisfy specific queries. Query and write requests across multiple partitions should be avoided if possible. A clustering column defines the sort order of rows within a partition. When defining a clustering column, consider the purpose of the data. For example, retrieving the most recent transactions, sorted by date, in descending order. in your keyspacekeyspace - The defining container for replication, similar to a schema in a relational database. All tables belong to a keyspace. Each keyspace can contain as many as 200 tables., a series of GraphQL objects are generated, along with queries and mutations that allow you to search and modify the table data.

📘

Note: If you haven't already, create a databasedatabase - A group of distributed instances for storing data. Each paid Astra database has at least three instances. using DataStax Astra.

We'll show you you how to:

About the GraphQL API endpoint

The Astra GraphQL API endpoint URL for your database is https://{databaseid}-{region}.apps.astra.datastax.com/api/graphql.
Each request must have a valid authorization 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 default naming convention for the GraphQL API converts CQL table and columncolumn - The smallest increment of data, which contains a name, a value, and a timestamp. Also known as a cell. names to lowerCamelCase for GraphQL fields and UpperCamelCase for GraphQL types. If the naming convention rules result in a naming conflict, a number suffix is appended to the name. For example, if someExistingColumn already exists, the column will be named someExistingColumn2 up to a maximum suffix value of 999. If there are additional naming conflicts, an error will be occur.

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 products the following fields and types are generated.

schema {
  query: Query
  mutation: Mutation
}

type Query {
  products(value: ProductsInput, orderBy: [ProductsOrder], options: QueryOptions): ProductsResult
  productsFilter(filter: ProductsFilterInput!, orderBy: [ProductsOrder], options: QueryOptions): ProductsResult
}

type Mutation {
  insertProducts(value: ProductsInput!, ifNotExists: Boolean, options: UpdateOptions): ProductsMutationResult
  updateProducts(value: ProductsInput!, ifExists: Boolean, ifCondition: ProductsFilterInput, options: UpdateOptions): ProductsMutationResult
  deleteProducts(value: ProductsInput!, ifExists: Boolean, ifCondition: ProductsFilterInput, options: UpdateOptions): ProductsMutationResult
}

Generated query types

The following query types are generated:

  • products(): Query product values by equality. If no value argument is provided then the first 100 (default pagesize) values are returned.
  • productsFilter: Query products values by filtering the result with additional operators. For example gt (greater than), lt (less than), in (in a list of values). The products() equality style query is preferable if your queries don't require non-equality operators.

Generated mutation types

The following mutations are generated:

  • insertProducts(): Insert a new product. This is an "upsert" operation that will update the value of existing products if they already exists unless ifNotExists is set to true. Using ifNotExists causes the mutation to use a lightweight transaction (LWT) adding significant overhead to the query.
  • updateProducts(): Update an existing product. This is also an "upsert" and will create a new product if one doesn't exists unless ifExists is set to true. Using ifExists or ifCondition causes the mutation to use a lightweight transaction (LWT) adding significant overhead to the query.
  • deleteProducts(): Deletes a product. Using ifExists or ifCondition causes the mutation to use a lightweight transaction (LWT) adding significant overhead to the query.

As more tables are added to your keyspace additional fields will be added to the Query and Mutation types to handle queries and mutations for those new tables.

Updated 21 days ago



Using the Astra GraphQL API


Astra has a GraphQL API that allows you to modify and query your table data.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.