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 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.
• Definir 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 da 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 poderá inferir campos se houver uma chave estrangeira.

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

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 seja exposta no GraphQL.
• Defina a vinculação de campos da origem para o destino por meio 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 um segundo relacionamento na entidade de destino que inverte os campos de origem e 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"

Isso emparelha com a relação Book para Author e habilita a travessia simétrica no GraphQL.

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

Suporte ao 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

• As relações exigem que as entidades existam no mesmo arquivo de configuração.
• Há suporte apenas para navegação de um único salto.
• Ciclos e aninhamento profundo não são otimizados.
• REST não dá suporte a relações (somente GraphQL).