Data Schema in Tailor Platform

This tutorial demonstrates how a data schema is mapped to GraphQL APIs.

  • Complete Quickstart first If you haven't yet built the Inventory Management System app from our template.

Data schema

A data model of your application is defined by the schema. Although multiple data models can be defined in one single schema file, we recommend using one or a few data models per one schema file for readability. See Tailor DB concept page to learn more about schema.

Tutorial steps

  1. Open GraphQL playground
  2. Open product.cue file in your repository
  3. See how the product.cue is mapped to the GraphQL APIs

1. Open GraphQL Playground

To get started, open the GraphQL playground by navigating to your Tailor Platform endpoint's URL and appending /playground at the end. For example, if your endpoint URL is https://your-endpoint.erp.dev, the GraphQL playground URL would be https://your-endpoint.erp.dev/playground.

Alternatively you can use our CLI to open the GraphQL playground in your browser.

<span><span style="color: var(--shiki-token-comment)"># Open the browser and open the GraphQL playground</span></span>
<span><span style="color: var(--shiki-token-function)">tailorctl</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">workspace</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">app</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">open</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">-n</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">ims</span></span>
<span></span>

2. Open product.cue file in your repository

In your application's repository, locate and open the product.cue file. This file contains the schema definition for the Product type. The schema will look like this:

<span><span style="color: var(--shiki-token-keyword)">package</span><span style="color: var(--shiki-color-text)"> master</span></span>
<span></span>
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> (</span></span>
<span><span style="color: var(--shiki-color-text)">	</span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">github.com/tailor-platform/tailorctl/schema/v2/tailordb</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">	</span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">tailor.build/template/services/tailordb</span><span style="color: var(--shiki-color-text)">:permissions</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">	</span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">tailor.build/template/services/tailordb</span><span style="color: var(--shiki-color-text)">:commonType</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">)</span></span>
<span></span>
<span><span style="color: var(--shiki-color-text)">Product: commonType.#CommonType </span><span style="color: var(--shiki-token-keyword)">&amp;</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">	Name:        </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Product</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">	Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Product model</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">	Fields: {</span></span>
<span><span style="color: var(--shiki-color-text)">		shopifyID: {</span></span>
<span><span style="color: var(--shiki-color-text)">			Type:        tailordb.#TypeString</span></span>
<span><span style="color: var(--shiki-color-text)">			Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Shopify product ID</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">		}</span></span>
<span><span style="color: var(--shiki-color-text)">		title: {</span></span>
<span><span style="color: var(--shiki-color-text)">			Type:        tailordb.#TypeString</span></span>
<span><span style="color: var(--shiki-color-text)">			Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Product title</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">		}</span></span>
<span><span style="color: var(--shiki-color-text)">		handle: {</span></span>
<span><span style="color: var(--shiki-color-text)">			Type:        tailordb.#TypeString</span></span>
<span><span style="color: var(--shiki-color-text)">			Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Product handle</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">		}</span></span>
<span><span style="color: var(--shiki-color-text)">		description: {</span></span>
<span><span style="color: var(--shiki-color-text)">			Type:        tailordb.#TypeString</span></span>
<span><span style="color: var(--shiki-color-text)">			Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Product description</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">		}</span></span>
<span><span style="color: var(--shiki-color-text)">		featuredImageID: {</span></span>
<span><span style="color: var(--shiki-color-text)">			Type:        tailordb.#TypeUUID</span></span>
<span><span style="color: var(--shiki-color-text)">			Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Featured image ID</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">		}</span></span>
<span><span style="color: var(--shiki-color-text)">		featuredImage: {</span></span>
<span><span style="color: var(--shiki-color-text)">			Type:        </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">ProductImage</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">			Description: </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">Featured image of the product</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">			SourceId:    </span><span style="color: var(--shiki-color-text)">&quot;</span><span style="color: var(--shiki-token-string-expression)">featuredImageID</span><span style="color: var(--shiki-color-text)">&quot;</span></span>
<span><span style="color: var(--shiki-color-text)">		}</span></span>
<span><span style="color: var(--shiki-color-text)">	}</span></span>
<span><span style="color: var(--shiki-color-text)">	TypePermission: permissions.editorAccess</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>

This file is written in CUE lang. CUE is a configuration language designed to simplify and unify configuration across different platforms and languages. It uses values and rules to define configurations and supports composition for easy reuse and maintenance.

To learn more about CUE, visit CUE basics.

3. See how the product.cue is mapped to the GraphQL APIs

Now that you've seen the schema definition in the product.cue file, let's explore how this maps to the GraphQL API. In the GraphQL playground, you can test the API with a query like the one below:

<span><span style="color: var(--shiki-token-keyword)">query</span><span style="color: var(--shiki-color-text)"> {</span></span>
<span><span style="color: var(--shiki-color-text)">  products {</span></span>
<span><span style="color: var(--shiki-color-text)">    collection {</span></span>
<span><span style="color: var(--shiki-color-text)">      id</span></span>
<span><span style="color: var(--shiki-color-text)">	  title</span></span>
<span><span style="color: var(--shiki-color-text)">      handle</span></span>
<span><span style="color: var(--shiki-color-text)">	  description</span></span>
<span><span style="color: var(--shiki-color-text)">      featuredImageID</span></span>
<span><span style="color: var(--shiki-color-text)">    }</span></span>
<span><span style="color: var(--shiki-color-text)">  }</span></span>
<span><span style="color: var(--shiki-color-text)">}</span></span>
<span></span>

This query will return a list of Product objects with the specified fields. You can see how the schema defined in the product.cue file is used to create the GraphQL API, allowing you to interact with your data easily.

You will notice some of the field like id is generated without specifically defined in product.cue. This is a pre-defined field and the name of the field is reserved. Please refer to Auto-generated fields.

Next steps

In the following tutorials, you'll learn how to modify the schema by adding fields to existing types or creating new types for your application.