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.
A full GraphQL schema that will bedeployed caninclude user-defined types (UDTs), object types, indexes, queries, mutations, and payloadtypes. The next sections describes the definition of these items before discussinghow to deploy the schema once created.
Do you want to understand deployment first?Read Deploy Schema.
A column's CQL data type is inferred from the GraphQL field type.GraphQL's built-in scalar types are mapped:
| GraphQL | CQL |
|---|---|
| ID | uuid |
| String | varchar |
| Int | int |
| Float | double |
| Boolean | boolean |
In addition, Stargate provides a set of custom scalar types that map directlyto the CQL types of the same name:Uuid, TimeUuid, Inet, Date, Duration, BigInt, Counter, Ascii, Decimal, Varint,Float32, Blob, SmallInt, TinyInt, Timestamp, Time.
Sets and lists are defined by custom typed arrays. Maps and tuples are notsupported, but UDTs can be used to create the same functionality.
In GraphQL syntax, square brackets denote an array, such as `email: [String]`defines a field named email that is an array of String values.Additionally, if an exclamation point follows a data type, such as `String!`,then the field cannot contain a null value.
Object types
The most basic components of a GraphQL schema are object types, which justrepresent a kind of object you can fetch from your service, and specify thefields contained in the object.Object types also havedirectives, whichare identifiers preceded by an `@` character.Directives are GraphQL server-specific, and implemented in the server.Stargate implements directives that are specific to the Apache Cassandrabackend, as well as Apollo data federation-specific directives that allow Stargateto work with the Apollo gateway.
Directives in example:
The fields author , reviews , address are defined as arrays by the addition of square brackets,`reviews: [Review] .Note that reviews and addresses are arrays of UDTswhereas author` is a list of Strings to name each author.
Create queries
Most types in your schema will just be normal object types, but there are two typesthat are special, the Query type and the Mutation type.Every GraphQL service has at least one query type.Mutation types are optional.
Queries
Create mutations
Mutations work in a similar way to queries.An input and output is defined.
The insert mutation will insert an object of the specified type, and the update and delete mutations will return a Boolean value.If the update or delete mutation names begin with those words, the `@cql_update` directiveis not required.
Conditional insertion
A mutation can be turned into a conditional insertion operation by ending the mutationname with ifNotExists .However, it may be useful to know if the insertion is successfully applied.In that case, see payload type below to see how a boolean field applied canbe added to the response from insertions or annotating it with `@cql_insert(ifNotExists: true)`.
Create payload types
Payloads types are not mapped to the database, and only serve as wrappers of an operation's response.They typically pass a more complex object than just an entity. For example,you can add fields that check the applied status for a conditional query, orthe pagingState .
In this example, a payload type SelectBookResult is created that accepts an arrayof books as the input. The associated query can use the required title and optional pagingState as input, and will return an array of books along with the pagingState .
Directives in example:
An example of retrieving data using this query is found xref:graphql-using-schema-first#retrievingdata[below].
Often, you wish to know if an operation was successful. Creating a payload type thatuses a boolean field applied can definitively answer if a conditional operationcompletes correctly.
Create a payload type that uses your standard object type as a field, along with applied :
If the conditional insert is successful (the row did not exist), then appliedwill be true and book will echo back the data that was just inserted;otherwise, applied will be false and book will be the existing data.