Skip to main content

Working with Shapes

Shapes are the schema objects that structure and store data in your project.

Shapes can be configured from the web client or by directly editing your schema file. Each method provides its own benefits: the web client is fast and easy, but allows for a more limited range of edits; editing the schema files requires more manual work, but allows for much more flexibility and power.

Working with shapes in the web client#

The easiest way to work with shapes in your project is through the TakeShape web client.

From any project, start by visiting the schema page. You'll see a table of shapes in your project, as well as an option to add a new one:

Clicking on any shape or clicking the Add Shape button will open the shape editor. Here, you can customize every aspect of your shape: update its name, change its model type, drag-and-drop new fields into your shape, and edit each field's properties.

When you have built-in services like Shopify connected to your project, you'll also be able to drag in fields and data from the connected service, too!

Automatically generated queries and mutations#

When you add or edit shapes in the web client, TakeShape will automatically create or update  queries and mutations that provide common functionality to your GraphQL API.

When creating a Single type shape, the web client will create a getShape query and an updateShape mutation. When creating Multiple or Taxonomy type shapes, the web client will also create a getShapeList query, as well as createShape and deleteShape mutations.

Working with shapes in the schema file#

You can directly edit your project schema to add shapes that work with data inside TakeShape or in connected services. This is the best way to add more complex fields and functionality that's not supported in the TakeShape web client, especially when dealing with connected GraphQL or REST services.

Start by exporting your schema file After editing your schema, you can then upload it to your project using the CLI or API.

All shapes should be added to the shapes top-level schema object. Since the schema is designed to be as flat as possible, each shape should be its own entry in the object. Shapes can be linked from inside other shapes' properties by using @ref and @relationship.

Shapes also contain their own sub-schema, under the schema key. This sub-schema contains a properties object for each data field in the shape.

In the following example, we'll add a "Product" model shape to our schema that uses data from a connected Shopify service:

First we'll add the basic metadata properties. The object key and name should match, the id can be any unique string, and the title can be human readable with spaces and punctuation, if desired.

Next, we set the model to use the "type": "multiple" configuration. This means that in our GraphQL API we will be able to add as many items as we like that use this shape, and we can query for paginated lists of this shape's items.

Finally, we start off with a simple shape schema that contains a single required property, name. We define a @mapping on name to tell TakeShape where it can find the data for this field. We're storing this field's value in TakeShape's data store, so we map the value to the data store table  takeshape:local:Product and name the column it will use, Column1.

Note: If you decide to change the name of the property later on, you'll need to keep the @mapping property the same, otherwise you'll lose data! You can always change the mapping to a new column, but note that the column will be empty after we create it.

Next, we'll add fields to support getting remote data from Shopify. To, we'll add:

The first field we're adding will allow us to set a specific Shopify Product ID on each shape item. It also has a validation regex pattern configured to validate data submitted on the field.

The second field is where things get interesting. Rather than define a static @mapping as our field's data source, we're configuring a Resolver on the field. It uses the value of the shopifyProductId field as an input argument to a query to a connected Shopify store. The value of this field will be dynamically resolved  whenever we query for a shape, based on the value of each shape's shopifyProductId.

Shape Spec#

We provide a complete spec for shapes and their sub-schemas in the Schema Spec Reference.

In Review#

  • The easiest way to work with Shapes is in the web client. The web client only creates Model Shapes, creates references to other shapes for you, and automatically generates queries and mutations for working with your Shape in the GraphQL API.
  • The most powerful way to work with Shapes is by directly editing your schema file. It allows you to specifically configure the data storage for your shape's data and supports dynamic ┬áresolution of properties using resolvers.