Relações de entidade no construtor de API de dados

As relações de entidade permitem que as consultas GraphQL percorram entidades relacionadas, permitindo formas de dados complexas com uma única consulta. Por exemplo:

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

Para conseguir isso, o DAB deve ser informado de como as entidades estão relacionadas por meio da relationships seção no arquivo de configuração.

Configuração

Para definir uma relação entre entidades:

• Use o relationships objeto dentro da configuração da entidade.
• Forneça o target.entity nome.
• Defina cardinality como "one" ou "many".
• Opcionalmente, especifique source.fields e target.fields.
• Use linking.object ao modelar relações muitos-para-muitos sem expor a tabela de junção.

Exemplo de CLI

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"

Exemplo de configuração

"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" ]
    }
  }
}

Um para muitos

• Use cardinalidade "many".
• Exemplo: A Series tem muitos Books.
• O DAB pode inferir campos se existir uma chave estrangeira.

dab update Series \
  --relationship books \
  --target.entity Book \
  --cardinality many

Relação muitos-para-um

• Use cardinalidade "one".
• Exemplo: A Book pertence a um Series.

dab update Book \
  --relationship series \
  --target.entity Series \
  --cardinality one

Muitos-para-Muitos (objeto de ligação)

• Use uma tabela de junção que não esteja exposta no GraphQL.
• Defina campos de ligação da origem ao destino através da tabela de junção.

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"

Muitos-para-Muitos (entidade de junção explícita)

• Exponha a tabela de junção como um objeto GraphQL.
• Defina relações em todas as três entidades.

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"

Relações recíprocas

Para permitir a navegação em ambas as direções (por exemplo, de Book para Author e de Author para Book), defina uma segunda relação na entidade de destino que inverta os campos de origem e de destino.

Exemplo

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"

Isto emparelha com a relação Book para Author e permite uma travessia simétrica no GraphQL:

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

Suporte a GraphQL

• Os campos relacionados aparecem como objetos aninhados.
• A cardinalidade determina se uma lista ou um único objeto é retornado.
• Os nomes de tipo e os campos do GraphQL correspondem aos nomes de configuração.

Limitações

• Os relacionamentos exigem que existam entidades no mesmo arquivo de configuração.
• Apenas a navegação de um só salto é suportada.
• Os ciclos e o aninhamento profundo não estão otimizados.
• O REST não suporta relacionamentos (somente GraphQL).