Entities

Definições de configuração para entidades de banco de dados.

Health

Description

Fields

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 o fields array não são usados. 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 dado do parâmetro é inferido. Parâmetros sem padrão podem ser omitidos.

object-description é uma descrição opcional legível por humanos do objeto de base de dados subjacente. Este valor é revelado durante a descoberta da ferramenta MCP, ajudando os agentes de IA a compreender o propósito 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>"
          }
        ]
      }
    }
  }
}

Parâmetros formato de array

No DAB 2.0 preview, parameters suporta um formato de array estruturado com metadados mais ricos. Cada parâmetro é um objeto com as seguintes propriedades:

Exemplo (formato de array — preferido)

{
  "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 do papel ao qual se aplicam as permissões. Use papéis de sistema (Anonymous, Authenticated) ou papéis personalizados definidos no seu fornecedor 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 papéis

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

named-role → authenticated → anonymous

• Se authenticated não estiver configurado para uma entidade, herda de anonymous.
• Se um papel nomeado não estiver configurado, herda de authenticated, ou de anonymous se authenticated também estiver ausente.

Isto significa que podes definir permissões uma vez ligado anonymous e que todos os papéis mais amplos têm o mesmo acesso automaticamente, sem necessidade de duplicação.

Example

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

Com esta configuração, anonymous, authenticated, e qualquer papel nomeado não configurado podem todos ler Book. dab configure --show-effective-permissions Use para ver as permissões resolvidas para cada entidade após a aplicação da herança.

Ações (string-array Permissions, entidades-nome, entidades)

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

* Atualmente, várias operações são suportadas 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 string, quando type=stored-procedure)

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

Example

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

Ações (objeto-matriz, Permissões, entidades-nome, entidades)

Uma matriz de objetos detalhando 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 base de dados filtram os resultados das consultas usando predicados ao estilo OData. Use @item.<field> para referenciar campos de entidade e @claims.<type> para injetar reivindicações autenticadas de utilizadores.

Tipo (entidades de nome de entidade 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 objeto. Quando type é uma cadeia simples, essa cadeia é usada como nome singular.

Example

Configuration

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

Consulta GraphQL

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

Resposta 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 GraphQL)

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

Format

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

Exemplo: operação

Quando operation está definido como query

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

Quando operation está definido como mutation

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

Ativado (entidades de nome de entidade 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 endpoints.

Format

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

Descrição (entidades com nome de entidade)

Uma descrição opcional legível por humanos da entidade. Este valor é apresentado na documentação gerada da API e como 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 com nome de entidade)

Define metadados para campos individuais da base de dados, incluindo aliases, descrições e designações de chaves primárias. O fields array substitui tanto mappings (através da alias propriedade) como source.key-fields (através da propriedade primary-key ) numa ú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 é designado como a chave primária (substituindo a necessidade de source.key-fields), enquanto sku_title e sku_status são aliasados 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 os níveis de cache utilizados:

Example

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

Relações (entidades de nome de entidade)

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

Propriedades aninhadas

Estas propriedades são usadas em diferentes combinações, 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 User, e 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 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

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

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

Esquema GraphQL

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

Linha de comandos

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 entrada 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 GraphQL

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

Linha de comandos

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 GraphQL

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

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

Linha de comandos

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"

Saúde (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 nome-entidade)

Controla a participação no MCP para a entidade. Quando o MCP está ativado globalmente, as entidades participam por defeito. Use esta propriedade para optar por não participar ou para ativar ferramentas MCP personalizadas para entidades de procedimentos armazenados.

Formato de objeto

Use o formato do objeto para controlo granular:

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

Ferramenta personalizada (apenas procedimentos armazenados)

Para entidades de procedimento armazenado, defina custom-tool para true registar 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 de 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