• Glossary
  • Support
  • Downloads
  • DataStax Home
Get Live Help
Expand All
Collapse All

DataStax Astra DB Classic Documentation

    • Overview
      • Release notes
      • Astra DB FAQs
      • Astra DB glossary
      • Get support
    • Getting Started
      • Grant a user access
      • Load and retrieve data
        • Use DSBulk to load data
        • Use Data Loader in Astra Portal
      • Connect a driver
      • Build sample apps
      • Use integrations
        • Connect with DataGrip
        • Connect with DBSchema
        • Connect with JanusGraph
        • Connect with Strapi
    • Planning
      • Plan options
      • Database regions
    • Securing
      • Security highlights
      • Security guidelines
      • Default user permissions
      • Change your password
      • Reset your password
      • Authentication and Authorization
      • Astra DB Plugin for HashiCorp Vault
    • Connecting
      • Connecting to a VPC
      • Connecting Change Data Capture (CDC)
      • Connecting CQL console
      • Connect the Spark Cassandra Connector to Astra
      • Drivers for Astra DB
        • Connecting C++ driver
        • Connecting C# driver
        • Connecting Java driver
        • Connecting Node.js driver
        • Connecting Python driver
        • Drivers retry policies
      • Connecting Legacy drivers
      • Get Secure Connect Bundle
    • Migrating
      • FAQs
      • Preliminary steps
        • Feasibility checks
        • Deployment and infrastructure considerations
        • Create target environment for migration
        • Understand rollback options
      • Phase 1: Deploy ZDM Proxy and connect client applications
        • Set up the ZDM Automation with ZDM Utility
        • Deploy the ZDM Proxy and monitoring
          • Configure Transport Layer Security
        • Connect client applications to ZDM Proxy
        • Manage your ZDM Proxy instances
      • Phase 2: Migrate and validate data
      • Phase 3: Enable asynchronous dual reads
      • Phase 4: Change read routing to Target
      • Phase 5: Connect client applications directly to Target
      • Additional resources
        • Glossary
        • Troubleshooting
          • Troubleshooting tips
          • Troubleshooting scenarios
        • Contribution guidelines
        • Release Notes
    • Managing
      • Managing your organization
        • User permissions
        • Pricing and billing
        • Audit Logs
        • Configuring SSO
          • Configure SSO for Microsoft Azure AD
          • Configure SSO for Okta
          • Configure SSO for OneLogin
      • Managing your database
        • Create your database
        • View your databases
        • Database statuses
        • Use DSBulk to load data
        • Use Data Loader in Astra Portal
        • Monitor your databases
        • Manage multiple keyspaces
        • Using multiple regions
        • Terminate your database
        • Resize your classic database
        • Park your classic database
        • Unpark your classic database
      • Managing with DevOps API
        • Managing database lifecycle
        • Managing roles
        • Managing users
        • Managing tokens
        • Managing multiple regions
        • Get private endpoints
        • AWS PrivateLink
        • Azure PrivateLink
        • GCP Private Service
    • Astra CLI
    • Developing with Stargate APIs
      • Develop with REST
      • Develop with Document
      • Develop with GraphQL
        • Develop with GraphQL (CQL-first)
        • Develop with GraphQL (Schema-first)
      • Develop with gRPC
        • gRPC Rust client
        • gRPC Go client
        • gRPC Node.js client
        • gRPC Java client
      • Develop with CQL
      • Tooling Resources
      • Node.js Document API client
      • Node.js REST API client
    • Stargate QuickStarts
      • Document API QuickStart
      • REST API QuickStart
      • GraphQL API CQL-first QuickStart
    • API References
      • DevOps REST API v2
      • Stargate Document API v2
      • Stargate REST API v2
  • DataStax Astra DB Classic Documentation
  • Developing with Stargate APIs
  • Develop with GraphQL

GraphQL API

Overview

The Stargate GraphQL API is implemented to easily modify and query your table data using GraphQL types, mutations, and queries with any Cassandra deployment.

The Stargate GraphQL API has two modes, one developed from native GraphQL schema principles, and one developed with the Cassandra Query Language (CQL) in mind. To distinguish these two modes, the rest of the documentation will refer to the modes as schema-first and cql-first.

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 columns defined, 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.

The schema-first approach allows you to create idiomatic GraphQL types, mutations, and queries in a manner familiar to GraphQL developers. The schema is deployed and can be updated by deploying a new schema without recreating the tables and columns directly. Under the covers, this approach will create and modify the CQL tables to match the GraphQL types. The schema can be modified for CQL decorated schema, such as specifying table and column names in Cassandra, while retaining GraphQL-centric names for the types that correspond. If you are a GraphQL developer, this approach is for you.

To compare the two approaches, let’s look at an example that creates a container (table or type) to hold information about a reader:

 cql-first
 reader: createTable(
  keyspaceName:"library",
  tableName:"reader",
  partitionKeys: [ { name: "name", type: {basic: TEXT} } ]
  # Secondary key used to access values within the partition
  clusteringKeys: [ { name: "user_id", type: {basic: UUID}, order: "ASC" } ]
  values: [
    { name: "birthdate", type: {basic: DATE} }
    { name: "email", type: {basic: SET, info:{ subTypes: [ { basic: TEXT } ] } } }
    { name: "reviews", type: {basic: TUPLE,
      info: { subTypes: [ { basic: TEXT }, { basic: INT }, { basic: DATE } ] } } }
    { name: "addresses", type: { basic: LIST,
      info: { subTypes: [ { basic: UDT, info: { name: "address_type", frozen: true } } ] } } }
    ]
  )
}
 schema-first
 type Reader @key @cql_entity(name: "reader") @cql_input {
  name: String! @cql_column(partitionKey: true)
  user_id: Uuid! @cql_column(clusteringOrder: ASC)
  birthdate: Date @cql_index(name: "date_idx")
  email: [String] @cql_column(typeHint: "set<varchar>")
  reviews: [Review] @cql_index(name: "review_idx", target: VALUES)
  address: [Address]
}

The two approaches are similar, in that both must name the columns (cql-first) or fields (schema-first). The data type must be specified for each column or field. Although the syntax of the data type is different, by comparing, you can see that they are similar. Each approach can define the primary key composed of one or more partition keys and zero or more clustering keys. The column reviews in the cql-first example is defined as a tuple, but since the schema-first approach doesn’t support tuples, a user-defined type Review is used instead. The UDTs are not included here for brevity, but are explained later.

The main difference in the two approaches shown here are the CQL directives included in the schema-first type. To extend the power of Cassandra, these directives allow a user to fine-tune, if you choose, how the type is defined in the underlying database.

The other difference, not illustrated here, is that, in the cql-first approach, mutations and queries are automatically generated, but no customization is possible. In the schema-first approach, the developer is responsible for declaring the mutations and queries, and so has the freedom to do whatever is needed for an application.

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

You can start with a GraphQL CQL-first QuickStart or follow the full instructions: (schema-first) (cql-first) .

We’ll show you you how to:

  1. Optional Create a user-defined type (UDT) (schema-first) (cql-first)

  2. Optional Delete a UDT (cql-first)

  3. Create object types (schema-first)

  4. Create table schema (cql-first)

  5. Delete table schema (cql-first)

  6. Optional Create indexes (schema-first) (cql-first)

  7. Deploy schema (schema-first)

  8. Undeploy schema (schema-first)

  9. Add data (schema-first) (cql-first)

  10. Get data (schema-first) (cql-first)

  11. Update data (schema-first) (cql-first)

  12. Delete data (schema-first) (cql-first)

About the GraphQL API endpoints

There are three Stargate GraphQL API endpoints, one for creating schema in cql-first, one for deploying schema in the graphql-first, and the third for querying or mutating a keyspace. The URLS are:

Schema

https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com:8080/api/graphql-schema

Admin

https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com:8080/api/graphql-admin

Querying

https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com:8080/api/graphql/{keyspace}

The schema endpoint is used to create or alter CQL schema in the cql-first GraphQL using direct schema manipulation. The admin endpoint is used to deploy GraphQL schema in the graphql-first GraphQL which will indirectly modify underlying CQL schema. The querying endpoint is constructed in the same manner for both graphql-first and cql-first.

Each request must have a valid Each request can also have an optional unique request id. The request id is recommended in a production environment and can be useful in troubleshooting issues.

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_

Using the GraphQL Playground

The easiest way to get started with GraphQL is to use the built-in GraphQL playground.

Add your 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:

  • /api/graphql-schema

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

  • /api/graphql/<keyspace>

    • An API for querying and modifying your tables using GraphQL fields. Generally, you will start the playground with /api/graphql-schema to create some schema.

Develop with Document Develop with GraphQL (CQL-first)

General Inquiries: +1 (650) 389-6000 info@datastax.com

© DataStax | Privacy policy | Terms of use

DataStax, Titan, and TitanDB are registered trademarks of DataStax, Inc. and its subsidiaries in the United States and/or other countries.

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries.

Kubernetes is the registered trademark of the Linux Foundation.

landing_page landingpage