Expose Data in a Collection¶
On this page
Overview¶
You can expose data from a MongoDB collection to client applications through the GraphQL API. Stitch automatically generates GraphQL types and resolvers based on the collection schema and enforces collection rules for all GraphQL operations.
Procedure¶
1. Configure Roles for the Collection¶
Stitch enforces collection rules for all incoming GraphQL requests, so you need to define at least one collection role with the permissions that your application requires.
All GraphQL requests include an authentication token that identifies the
logged in Stitch user that sent the request. Stitch evaluates a role for
every document included in a GraphQL operation and only returns fields
and documents that the user has permission to see. If Stitch omits a
field, the field has a null
value in the returned document.
2. Define a Schema for Documents in the Collection¶
GraphQL requires that all data conforms to a well-defined type, so you must define a schema for documents in the collection. Stitch automatically generates GraphQL types and resolvers for documents in the collection based on the collection schema and regenerates new types whenever the schema changes.
Automatically Generate a Schema
Stitch can generate a collection schema for you based on a sample of existing documents in the collection. If you don’t have existing data, you can insert a new document that has a mock implementation of the fields you want to include in your schema and then generate a schema based on the mock.
3. Define Relationships to Other Collections¶
You can use a collection schema to define relationships that connect each document in the local collection to one or more documents in a foreign collection. The foreign collection can be any collection in the same linked MongoDB Atlas cluster as the local collection, including the local collection itself.
Relationships allow you to fluently reference and query related
documents in GraphQL read and write operations. For example, you can
query for a person and include the full document for each of their
children from the same people
collection:
Stitch evaluates which foreign documents are related to a given local document based on a foreign key value. For each relationship, the local document contains either a single foreign key value or an array of foreign key values in a specific field. A document is related to any documents in the foreign collection where the value of the foreign key field matches a foreign key included in the local field.
Relationship definitions have the following form:
Field Name | Type | Description |
---|---|---|
<Local Field Name> |
String | The name of a field defined in the local collection |
ref |
String | A path that specifies the foreign collection that contains the related documents. |
foreign_key |
String | The field name that contains the reference value for each
document in the foreign collection. A document in the foreign
collection is related if its foreign_key value matches the
local field value. |
is_list |
Boolean | Indicates whether the relationship is to a single document or
multiple documents. If A relationship is not valid if |
Example
Consider an application that has two collections:
The
accounts
collection contains documents that each describe a customer account.The
customers
collection contains documents that each describe a single customer that can have one or more accounts. Every document in thecustomers
collection has anaccounts
field that contains an array of everyaccount_id
value from theaccounts
collection that applies to the customer.
The app defines this relationship on the customers
collection. It
points from the array of account id values stored in the accounts
field to the account_id
field of each document in the
accounts
collection.
With this relationship defined, Stitch can fluidly return a customer and all of their accounts in the same GraphQL query.
4. Name the Data Type¶
Stitch names the GraphQL types that it generates based on the data type
that documents in the collection conform to. You can configure the name
of the GraphQL types by setting the title
field in a schema to the
name of the data type that the schema defines.
Default Type Names
If you automatically generate a collection schema, Stitch includes a
pre-defined title
field that uses the singularized form of the
collection name. For example, a schema generated for the movies
collection would have its title
set to movie
by default.
Stitch uses the same rules as Rails ActiveSupport to singularize most common English nouns. If Stitch cannot singularize the collection name, it will use the collection name verbatim.
There are three situations where you can set the title
field:
- You can define the type name for each document in a collection by
setting
title
at the root level of the schema. If you don’t specify a title, Stitch uses the name of the collection instead. - You can define the type name for an embedded object by setting
title
in the embedded object schema. - You can define the type name for a field that has a defined
relationship by setting
title
in the field schema. Stitch uses thetitle
instead of the defined field name when it resolves relationships in GraphQL.
Singular and Plural Types
Stitch generates two GraphQL queries for each collection:
- A singular query that finds a specific document in the collection. The
query uses the same name as the schema’s
title
. If the schema’stitle
is a plural noun, Stitch attempts to use its singular form as determined by the Rails ActiveSupport inflection rules. - A plural query that finds a subset of all documents in the collection.
If possible, the query uses the plural form of the singular query name. If
Stitch is unable to pluralize the name or if the pluralized name is the
same as the singular name, the plural query uses the same name as the
singular query with an additional
"s"
appended to the end.
Example
The following schema is configured for the laboratory.mice
collection:
Stitch generates two queries, mouse
(singular) and mice
(plural),
based on the schema:
Next Steps¶
Once you’ve defined a schema for the collection, Stitch automatically exposes the documents in the collection through the GraphQL API. You can now connect from a client application and execute GraphQL operations like queries and mutations.
To configure validation for read and write operations explore your data with the GraphiQL explorer, navigate to the GraphQL screen in the Stitch UI.