Relações de entidade no Data API builder

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

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

Para alcançar este comportamento, o DAB deve ser informado sobre como as entidades estão relacionadas através da relationships secção no ficheiro de configuração.

Configuração

Para definir uma relação entre entidades:

• Use o relationships objeto dentro da configuração da entidade.
• Dê o target.entity nome.
• Defina cardinality como "one" ou "many".
• Opcionalmente, especificar 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

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 associação)

• Usa 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)

• Expõe 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), definam uma segunda relação na entidade-alvo que inverte 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"

Esta configuração emparelha-se com a relação Book a Author e permite a travessia simétrica em GraphQL.

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

Suporte a GraphQL

• Campos relacionados aparecem como objetos aninhados.
• A cardinalidade determina se uma lista ou um único objeto é devolvido.
• Os nomes e campos dos tipos GraphQL correspondem aos nomes das configurações.

Limitações

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