Navigation

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:

copy 
query {
  person(query: { name: "Molly Weasley" }) {
    _id
    name
    age
    picture
    children {
      _id
      name
      age
      picture
    }
  }
}

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:

copy 
{
  "<Local Field Name>": {
    "ref": "#/stitch/<Cluster>/<Database>/<Collection>",
    "foreign_key": "<Foreign Key Field Name>",
    "is_list": <Boolean>
  }
}
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 true, the local field contains an array of values. Otherwise, the field contains a single value.

A relationship is not valid if is_list is true but your schema does not define the field as an array (or vice-versa).

Example

Consider an application that has two collections:

  • The accounts collection contains documents that each describe a customer account.

    copy
    Account Collection Schema
    {
  "title": "Account",
  "properties": {
    "_id": { "bsonType": "objectId" },
    "account_id": { "bsonType": "string" },
    "products": {
      "bsonType": "array",
      "items": { "bsonType": "string" }
    },
    ...
  }
}

  • The customers collection contains documents that each describe a single customer that can have one or more accounts. Every document in the customers collection has an accounts field that contains an array of every account_id value from the accounts collection that applies to the customer.

    copy
    Customer Collection Schema
    {
  "title": "Customer",
  "properties": {
    "username": { "bsonType": "string" },
    "accounts": {
      "bsonType": "array",
      "items": { "bsonType": "string" }
    },
    ...
  }
}

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.

copy 
{
  "accounts": {
    "ref": "#/stitch/mongodb-atlas/sample_analytics/accounts",
    "foreign_key": "account_id",
    "is_list": true
  }
}

With this relationship defined, Stitch can fluidly return a customer and all of their accounts in the same GraphQL query.

copy 
query CustomerAccounts {
  customer(query: { username: "Elizabeth Ray" }) {
    username
    accounts {
      account_id
      products
    }
  }
}

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 the title instead of the defined field name when it resolves relationships in GraphQL.
copy 
{
  "title": "movie",
  "properties": {
    "_id": { "bsonType": "objectId" },
    "title": { "bsonType": "string" },
    "year": { "bsonType": "int" },
    "director": { "bsonType": "int" }
  }
}

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’s title 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:

copy 
{
  "title": "Mouse",
  "bsonType": "object",
  "properties": {
    "_id": { "bsonType": "objectId" },
    "name": { "bsonType": "string" },
    "age": { "bsonType": "int" }
  }
}

Stitch generates two queries, mouse (singular) and mice (plural), based on the schema:

copy 
query Mice {
  mouse(query: { _id: "5ebe6819197003ddb1f74475" }) {
    name
    age
  }
  mice {
    name
    age
  }
}

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.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.