Edit

Share via

Entity relationships in Data API builder

Entity relationships allow GraphQL queries to traverse related entities, enabling complex data shapes with a single query. For example:

{
  books {
    items {
      id
      title
      authors {
        items {
          first_name
          last_name
        }
      }
    }
  }
}

To achieve this, DAB must be told how entities are related via the relationships section in the configuration file.

Configuration

To define a relationship between entities:

  • Use the relationships object inside the entity configuration.
  • Provide the target.entity name.
  • Set cardinality as "one" or "many".
  • Optionally specify source.fields and target.fields.
  • Use linking.object when modeling many-to-many relationships without exposing the join table.

CLI example

dab update Book \
  --relationship authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "book_id" \
  --linking.target.fields "author_id"

Configuration example

"Book": {
  "source": "dbo.books",
  "relationships": {
    "authors": {
      "cardinality": "many",
      "target.entity": "Author",
      "source.fields": [ "id" ],
      "target.fields": [ "id" ],
      "linking.object": "dbo.books_authors",
      "linking.source.fields": [ "book_id" ],
      "linking.target.fields": [ "author_id" ]
    }
  }
}

One-to-Many

  • Use cardinality "many".
  • Example: A Series has many Books.
  • DAB can infer fields if a foreign key exists.
dab update Series \
  --relationship books \
  --target.entity Book \
  --cardinality many

Many-to-One

  • Use cardinality "one".
  • Example: A Book belongs to one Series.
dab update Book \
  --relationship series \
  --target.entity Series \
  --cardinality one

Many-to-Many (linking object)

  • Use a join table that is not exposed in GraphQL.
  • Define linking fields from source to target via the join table.
dab update Author \
  --relationship books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "author_id" \
  --linking.target.fields "book_id"

Many-to-Many (explicit join entity)

  • Expose the join table as a GraphQL object.
  • Define relationships on all three entities.
dab add BookAuthor \
  --source dbo.books_authors \
  --permissions "anonymous:*"

dab update BookAuthor \
  --relationship book \
  --target.entity Book \
  --cardinality one \
  --relationship.fields "book_id:id"

dab update BookAuthor \
  --relationship author \
  --target.entity Author \
  --cardinality one \
  --relationship.fields "author_id:id"

Reciprocal relationships

To allow navigation in both directions (for example, from Book to Author and from Author to Book), define a second relationship on the target entity that reverses the source and target fields.

Example

dab update Author \
  --relationship books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "author_id" \
  --linking.target.fields "book_id"

This pairs with the Book to Author relationship and enables symmetric traversal in GraphQL:

{
  authors {
    items {
      first_name
      books {
        items {
          title
        }
      }
    }
  }
}

GraphQL support

  • Related fields appear as nested objects.
  • Cardinality determines whether a list or single object is returned.
  • GraphQL type names and fields match configuration names.

Limitations

  • Relationships require entities to exist in the same config file.
  • Only one-hop navigation is supported.
  • Cycles and deep nesting aren't optimized.
  • REST doesn't support relationships (GraphQL only).
  • Last updated on