Entities

Opciones de configuración para entidades de base de datos.

Health

Description

Campos

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

Introducción al 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
      }
    }
  }
}

Origen (entidades de nombre de entidad)

Detalles del origen de la base de datos de la entidad.

Propiedades anidadas

* key-fields solo es necesario cuando type es view y la fields matriz no se usa. El valor representa las claves principales.

** parameters solo es necesario cuando type es stored-procedure y solo para parámetros con valores predeterminados. El tipo de datos del parámetro se deduce. Los parámetros sin un valor predeterminado se pueden omitir.

object-description es una descripción opcional legible del objeto de base de datos subyacente. Este valor se muestra durante la detección de herramientas de MCP, lo que ayuda a los agentes de inteligencia artificial a comprender el propósito de la entidad.

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

En la versión preliminar de DAB 2.0, parameters admite un formato de matriz estructurado con metadatos más completos. Cada parámetro es un objeto con las siguientes propiedades:

Ejemplo (formato de matriz, 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"
          }
        ]
      }
    }
  }
}

Permisos (entidades de nombre de entidad)

Especifica el nombre del rol al que se aplican los permisos. Use roles de sistema (Anonymous, Authenticated) o roles personalizados definidos en el proveedor de identidades.

Format

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

Example

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

Herencia de roles

DAB 2.0 presenta la herencia de roles para los permisos de entidad. Cuando un rol no está configurado explícitamente para una entidad, hereda los permisos de un rol más amplio mediante la cadena siguiente:

named-role → authenticated → anonymous

• Si authenticated no está configurado para una entidad, hereda de anonymous.
• Si un rol con nombre no está configurado, hereda de authenticatedo de anonymous si authenticated también está ausente.

Esto significa que puede definir permisos una vez en anonymous y cada rol más amplio obtiene automáticamente el mismo acceso, sin que se requiera duplicación.

Example

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

Con esta configuración, anonymous, authenticatedy cualquier rol con nombre no configurado puede leer Book. Use dab configure --show-effective-permissions para ver los permisos resueltos para cada entidad después de aplicar la herencia.

Acciones (entidades de nombre de entidad de permisos de matriz de cadenas)

Matriz de cadenas que detalla qué operaciones se permiten para el rol asociado.

* Actualmente solo se admiten varias operaciones en GraphQL.

Format

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

Example

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

Formato alternativo (solo cadena, cuando type=stored-procedure)

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

Example

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

Acciones (entidades de nombre de entidad permisos de matriz de objetos)

Matriz de objetos que detalla qué operaciones se permiten para el rol asociado.

Propiedades anidadas

Format

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

Example

Esto concede read permiso para auditor en la User entidad, con restricciones de campo y directiva.

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

Notas de la directiva

Las directivas de base de datos filtran los resultados de la consulta mediante predicados de estilo OData. Use @item.<field> para hacer referencia a campos de entidad e @claims.<type> insertar notificaciones de usuario autenticadas.

Tipo (entidades de nombre de entidad de GraphQL)

Establece la convención de nomenclatura de una entidad dentro del esquema de GraphQL.

Format

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

Propiedades anidadas

* singular es necesario cuando type se especifica como un objeto . Cuando type es una cadena sin formato, esa cadena se usa como nombre singular.

Example

Configuration

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

Consulta de GraphQL

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

Respuesta de GraphQL

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

Operación (entidades de nombre de entidad de GraphQL)

Designa si la stored-procedure operación aparece en o QueryMutation.

Format

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

Ejemplo: operación

Cuando operation se establece en query

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

Cuando operation se establece en mutation

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

Habilitado (entidades de nombre de entidad de GraphQL)

Permite a los desarrolladores incluir de forma selectiva entidades en el esquema graphQL.

Format

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

REST (entidades de nombre de entidad)

* La methods propiedad es solo para stored-procedure los puntos de conexión.

Format

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

Descripción (entidades de nombre de entidad)

Descripción opcional legible de la entidad. Este valor aparece en la documentación de API generada y como comentario en el 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 nombre de entidad)

Define metadatos para campos de base de datos individuales, incluidos alias, descripciones y designaciones de clave principal. La fields matriz reemplaza mappings (a través de la alias propiedad) y source.key-fields (a través de la primary-key propiedad) en una única estructura unificada.

Propiedades anidadas

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

En este ejemplo, id se designa como la clave principal (reemplazando la necesidad de source.key-fields), mientras que sku_title y tienen un alias como sku_status y titlestatus (reemplazando la necesidad de mappings).

Asignaciones (entidades de nombre de entidad)

Habilita alias personalizados o nombres expuestos para campos de objeto de base de datos.

Format

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

Examples

Tabla de base de datos

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

Configuration

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

Caché (entidades de nombre de entidad)

Habilita y configura el almacenamiento en caché de la entidad.

Propiedades anidadas

Format

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

La level propiedad controla qué niveles de caché se usan:

Example

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

Relaciones (entidades de nombre de entidad)

Configura cómo se relacionan las entidades de GraphQL con otras entidades expuestas. Para obtener más información, consulte desglose de las relaciones del generador de datos.

Propiedades anidadas

Estas propiedades se usan en combinaciones diferentes en función de la cardinalidad de la relación.

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

Ejemplo: Cardinalidad uno a uno

Cada Profile uno está relacionado exactamente con un Usery cada uno User tiene exactamente uno relacionado Profile.

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

Esquema de GraphQL

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

Command-line

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

Ejemplo: cardinalidad uno a varios

Un Category puede tener una o varias entidades relacionadas Book , mientras que cada Book una puede tener una relacionada Category.

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

Esquema de GraphQL

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

Línea de comandos

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

Ejemplo: Cardinalidad de varios a uno

Muchas Book entidades pueden tener una relacionada Category, mientras que una Category puede tener una o varias entradas relacionadas Book .

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

Esquema de GraphQL

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

Línea de comandos

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

Ejemplo: Cardinalidad de varios a varios

Muchas Book entidades pueden tener muchas entidades relacionadas Author , mientras que muchas entidades pueden tener muchas Author 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 de GraphQL

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

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

Línea 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"

Estado (entidades de nombre de entidad)

Habilita y configura las comprobaciones de estado de la entidad.

Propiedades anidadas

Example

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

MCP (entidades de nombre de entidad)

Controla la participación de MCP para la entidad. Cuando MCP está habilitado globalmente, las entidades participan de forma predeterminada. Use esta propiedad para rechazar o habilitar herramientas de MCP personalizadas para entidades de procedimiento almacenado.

Formato de objeto

Use el formato de objeto para el control granular:

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

Herramienta personalizada (solo procedimientos almacenados)

En el caso de las entidades de procedimiento almacenado, establezca en custom-tooltrue para registrar el procedimiento como una herramienta MCP con nombre:

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

Ejemplos de la 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