Schema-specific queries

When you define a schema, TinaCMS will generate a GraphQL API which treats your local filesystem as a database. You can serve this schema locally via the CLI or you can consume it from Tina Cloud.

The GraphQL API will generate queries which are specific to the schema you define.

Available queries:

• get<collection>Document
• get<collection>List

Available mutations

• update<collection>Document
• addPendingDocument

For a given collection, it's name will be used to generate get<collection>Document and get<collection>List queries, and the update<collection>Document mutation.

Example schema

Using the following schema, we'll show you how each of the queries/mutations can be used.

// .tina/schema.ts
import { defineSchema } from '@tinacms/cli'

export default defineSchema({
  collections: [
    {
      label: 'Blog Posts',
      name: 'post',
      path: 'content/posts',
      format: 'json',
      fields: [
        {
          type: 'string',
          label: 'Title',
          name: 'title',
        },
        {
          type: 'string',
          label: 'Category',
          name: 'category',
        },
        {
          type: 'reference',
          label: 'Author',
          name: 'author',
          collections: ['author'],
        },
      ],
    },
    {
      label: 'Authors',
      name: 'author',
      format: 'json',
      path: 'content/authors',
      fields: [
        {
          type: 'string',
          label: 'Name',
          name: 'name',
        },
        {
          type: 'string',
          label: 'Avatar',
          name: 'avatar',
        },
      ],
    },
  ],
})

Querying a single document with get<collection>Document

Get a single document, providing it's relativePath as the argument. relativePath is the portion of the path relative to the collection's path. So in this example, the post collection has a path of content/posts. And your document can be found at content/posts/voteForPedro.md, so relativePath: "voteForPedro.md". If your item was at content/posts/nested-folder/voteForPedro.md you'd specify: relativePath: "nested-folder/voteForPedro.md".

Our collections for the above schema are named "post" and "author", so we can query for each using the getPostDocument & getAuthorDocument

Querying a list of documents with get<collection>List

List queries offer limited functionality for now.

• Because of the nature of list items, we don't currently auto-generate Tina forms for these queries.
• Depending on how many items you may have in your collection, the query could be quite slow. We'll be working on a more robust data layer to improve this experience in the near future.

Here we will query our post collection with getPostList

Updating a document with update<collection>Document

Our collections for the above schema are named "post" and "author", so we can apply an update to each collection type using the updatePostDocument & updateAuthorDocument

Note: Update mutations will overwrite all fields. Omitting a field will result in it being nullified.

Adding a document with addPendingDocument

The addPendingDocument mutation will take in the collection name as a parameter, as well as the new relative path.

Note: addPendingDocument does not currently support fields of any kind, just creating the record.

Ready to try out some of these queries using your specific schema? Try running the Tina CLI and testing them out using the Altair client

General queries

As an alternative to the schema-specific queries, the GraphQL API also makes the following general queries available:

• getDocument
• getCollections
• getCollection
• addPendingDocument
• updateDocument