Entities

Configurações para entidades de banco de dados.

Health

Description

Campos

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

Visão geral do formato

{
  "entities": {
    "{entity-name}": {
      "description": <string>,
      "rest": {
        "enabled": <boolean> // default: true
        "path": <string> // default: "{entity-name}"
        "methods": ["GET", "POST"] // default: ["GET", "POST"]
      },
      "graphql": {
        "enabled": <boolean> // default: true
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" | "mutation" // default: "query"
      },
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      },
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ],
      "mappings": { // DEPRECATED: use fields[].alias
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": <string>,
          "source.fields": [<string>],
          "target.fields": [<string>],
          "linking.object": <string>,
          "linking.source.fields": [<string>],
          "linking.target.fields": [<string>]
        }
      },
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | <custom-role>,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": [<string>],
            "exclude": [<string>]
          },
          "policy": {
            "database": <string>
          }
        }
      ],
      "cache": {
        "enabled": <boolean>,
        "ttl-seconds": <integer>,
        "level": "L1" | "L1L2" // default: "L1L2"
      },
      "mcp": {
        "dml-tools": <boolean>,       // default: true
        "custom-tool": <boolean>      // stored-procedure only; default: false
      }
    }
  }
}

Origem (entidades de nome de entidade)

Os detalhes da fonte do banco de dados da entidade.

Propriedades aninhadas

* key-fields só é necessário quando type é view e a fields matriz não é usada. O valor representa as chaves primárias.

** parameters só é necessário quando type é stored-procedure e somente para parâmetros com valores padrão. O tipo de dados do parâmetro é inferido. Parâmetros sem um padrão podem ser omitidos.

object-description é uma descrição opcional legível por humanos do objeto de banco de dados subjacente. Esse valor é exibido durante a descoberta da ferramenta MCP, ajudando os agentes de IA a entender a finalidade da entidade.

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      }
    }
  }
}

Formato de matriz de parâmetros

Na versão prévia do DAB 2.0, parameters dá suporte a um formato de matriz estruturada com metadados mais avançados. Cada parâmetro é um objeto com as seguintes propriedades:

Exemplo (formato de matriz — preferencial)

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "default": null,
            "description": "The unique identifier of the book"
          }
        ]
      }
    }
  }
}

Permissões (entidades de nome de entidade)

Especifica o nome da função ao qual as permissões se aplicam. Use funções do sistema (Anonymous, Authenticated) ou funções personalizadas definidas em seu provedor de identidade.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"Anonymous" | "Authenticated" | "custom-role">,
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "reader",
          "actions": ["read"]
        }
      ]
    }
  }
}

Herança de função

O DAB 2.0 introduz a herança de função para permissões de entidade. Quando uma função não está explicitamente configurada para uma entidade, ela herda permissões de uma função mais ampla usando a seguinte cadeia:

named-role → authenticated → anonymous

• Se authenticated não estiver configurado para uma entidade, ela herdará de anonymous.
• Se uma função nomeada não estiver configurada, ela herdará de authenticated, ou de anonymous se authenticated também estiver ausente.

Isso significa que você pode definir permissões uma vez e anonymous cada função mais ampla obtém o mesmo acesso automaticamente, sem necessidade de duplicação.

Example

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

Com essa configuração, anonymouse authenticatedqualquer função nomeada não configurada pode ser lida Book. Use dab configure --show-effective-permissions para ver as permissões resolvidas para cada entidade após a aplicação da herança.

Ações (entidades de nome de entidade de permissões de matriz de cadeia de caracteres)

Uma matriz de cadeia de caracteres que detalha quais operações são permitidas para a função associada.

* No momento, há suporte para várias operações apenas no GraphQL.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ "*" ] // equivalent to create, read, update, delete
        }
      ]
    }
  }
}

Formato alternativo (somente cadeia de caracteres, quando type=stored-procedure)

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": <string>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": "*" // equivalent to execute
        }
      ]
    }
  }
}

Ações (entidades de nome de entidade de permissões de matriz de objeto)

Uma matriz de objetos que detalha quais operações são permitidas para a função associada.

Propriedades aninhadas

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }

Example

Isso concede read permissão à auditorUser entidade, com restrições de campo e política.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Notas de política

As políticas de banco de dados filtram os resultados da consulta usando predicados no estilo OData. Use @item.<field> para referenciar campos de entidade e @claims.<type> injetar declarações de usuário autenticadas.

Tipo (entidades de nome de entidade do GraphQL)

Define a convenção de nomenclatura para uma entidade dentro do esquema GraphQL.

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "type": {
          "singular": "<string>",
          "plural": "<string>"
        }
      }
    }
  }
}

Propriedades aninhadas

* singular é necessário quando type é especificado como um objeto. Quando type é uma cadeia de caracteres simples, essa cadeia de caracteres é usada como o nome singular.

Example

Configuration

{
  "entities": {
    "User": {
      "graphql": {
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

Consulta GraphQL

{
  Users {
    items {
      id
      name
      age
      isAdmin
    }
  }
}

Resposta do GraphQL

{
  "data": {
    "Users": {
      "items": [
        {
          "id": 1,
          "name": "Alice",
          "age": 30,
          "isAdmin": true
        },
        {
          "id": 2,
          "name": "Bob",
          "age": 25,
          "isAdmin": false
        }
        // ...
      ]
    }
  }
}

Operação (entidades de nome de entidade do GraphQL)

Designa se a stored-procedure operação é exibida sob o Query ou Mutation.

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "operation": "query" | "mutation"
      }
    }
  }
}

Exemplo: operação

Quando operation é definido como query

type Query {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Quando operation é definido como mutation

type Mutation {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Habilitado (entidades de nome de entidade do GraphQL)

Permite que os desenvolvedores incluam seletivamente entidades no esquema GraphQL.

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST (entidades de nome de entidade)

* A methods propriedade é apenas para stored-procedure pontos de extremidade.

Format

{
  "entities": {
    "{entity-name}": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "{entity-name}">
      }
    }
  }
}

Descrição (entidades de nome de entidade)

Uma descrição opcional legível por humanos da entidade. Esse valor é exibido na documentação da API gerada e como um comentário no esquema graphQL.

Format

{
  "entities": {
    "{entity-name}": {
      "description": "<string>"
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "description": "Represents a book in the catalog with title, author, and pricing information.",
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

Campos (entidades de nome de entidade)

Define metadados para campos de banco de dados individuais, incluindo aliases, descrições e designações de chave primária. A fields matriz substitui ambos mappings (por meio da alias propriedade) e source.key-fields (por meio da primary-key propriedade) em uma única estrutura unificada.

Propriedades aninhadas

Format

{
  "entities": {
    "{entity-name}": {
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      },
      "fields": [
        {
          "name": "id",
          "description": "Unique book identifier",
          "primary-key": true
        },
        {
          "name": "sku_title",
          "alias": "title",
          "description": "The display title of the book"
        },
        {
          "name": "sku_status",
          "alias": "status"
        }
      ]
    }
  }
}

Neste exemplo, id é designada como a chave primária (substituindo a necessidade de source.key-fields), enquanto sku_title e sku_status são aliased como title e status (substituindo a necessidade de mappings).

Mapeamentos (entidades de nome de entidade)

Habilita aliases personalizados ou nomes expostos para campos de objeto de banco de dados.

Format

{
  "entities": {
    "{entity-name}": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

Examples

Tabela de banco de dados

CREATE TABLE Books
(
  id INT,
  sku_title VARCHAR(50),
  sku_status VARCHAR(50),
)

Configuration

{
  "entities": {
    "Books": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

Cache (entidades de nome de entidade)

Habilita e configura o cache para a entidade.

Propriedades aninhadas

Format

{
  "entities": {
    "{entity-name}": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>,
        "level": <"L1" | "L1L2"> (default: "L1L2")
      }
    }
  }
}

A level propriedade controla quais camadas de cache são usadas:

Example

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30,
        "level": "L1"
      }
    }
  }
}

Relações (entidades de nome de entidade)

Configura como as entidades do GraphQL estão relacionadas a outras entidades expostas. Para obter mais informações, consulte divisão de relações do construtor de API de Dados.

Propriedades aninhadas

Essas propriedades são usadas em combinações diferentes dependendo da cardinalidade da relação.

Format

{
  "entities": {
    "{entity-name}": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

Exemplo: cardinalidade um-para-um

Cada Profile um está relacionado a exatamente um Usere cada User um tem exatamente um relacionado Profile.

{
  "entities": {
    "User": {
      "relationships": {
        "user_profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    },
    "Profile": {
      ...
    }
  }
}

Esquema do GraphQL

type User
{
  id: Int!
  ...
  profile: Profile
}

Command-line

dab update User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Exemplo: cardinalidade um-para-muitos

Uma Category pode ter uma ou mais entidades relacionadas Book , enquanto cada Book uma pode ter uma relacionada Category.

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

Esquema do GraphQL

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

Linha de comando

dab update Category \
  --relationship category_books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:category_id"

Exemplo: cardinalidade muitos para um

Muitas Book entidades podem ter uma relacionada Category, enquanto uma Category pode ter uma ou mais entradas relacionadas Book .

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

Esquema do GraphQL

type Book
{
  id: Int!
  ...
  category: Category
}

Linha de comando

dab update Book \
  --relationship books_category \
  --target.entity "Category" \
  --cardinality one \
  --relationship.fields "category_id:id"

Exemplo: cardinalidade muitos para muitos

Muitas Book entidades podem ter muitas entidades relacionadas Author , enquanto muitas Author entidades podem ter muitas entradas relacionadas Book .

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_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" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

Esquema do GraphQL

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

Linha de comando

dab update Book \
  --relationship books_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"

Integridade (entidades de nome de entidade)

Habilita e configura verificações de integridade para a entidade.

Propriedades aninhadas

Example

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}

MCP (entidades de nome de entidade)

Controla a participação do MCP para a entidade. Quando o MCP é habilitado globalmente, as entidades participam por padrão. Use essa propriedade para recusar ou habilitar ferramentas MCP personalizadas para entidades de procedimento armazenado.

Formato do objeto

Use o formato de objeto para controle granular:

{
  "entities": {
    "Book": {
      "mcp": {
        "dml-tools": true
      }
    }
  }
}

Ferramenta personalizada (somente procedimentos armazenados)

Para entidades de procedimento armazenado, defina custom-tool para true registrar o procedimento como uma ferramenta MCP nomeada:

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Exemplos da CLI

dab add Book --source books --permissions "anonymous:*" --mcp.dml-tools true

dab add GetBookById --source dbo.get_book_by_id --source.type stored-procedure --permissions "anonymous:execute" --mcp.custom-tool true