Entities

データベース エンティティの構成設定。

Health

Description

Fields

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

書式の概要

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

ソース (エンティティ名エンティティ)

エンティティのデータベース ソースの詳細。

入れ子になったプロパティ

* key-fields は、 type が view され、 fields 配列が使用されていない場合にのみ必要です。 値は主キーを表します。

** parameters は、 type が stored-procedure されている場合にのみ必要であり、既定値を持つパラメーターに対してのみ必要です。 パラメーターのデータ型が推論されます。 既定値のないパラメーターは省略できます。

object-description は、基になるデータベース オブジェクトの人間が判読できる省略可能な説明です。 この値は、MCP ツールの検出中に表示され、AI エージェントがエンティティの目的を理解するのに役立ちます。

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

パラメーター配列の形式

DAB 2.0 プレビューでは、 parameters はより豊富なメタデータを含む構造化された配列形式をサポートしています。 各パラメーターは、次のプロパティを持つオブジェクトです。

例 (配列形式 - 推奨)

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

アクセス許可 (エンティティ名エンティティ)

アクセス許可を適用するロール名を指定します。 ID プロバイダーで定義されているシステム ロール (Anonymous、 Authenticated) またはカスタム ロールを使用します。

Format

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

Example

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

ロールの継承

DAB 2.0 では、エンティティのアクセス許可にロールの継承が導入されています。 エンティティに対してロールが明示的に構成されていない場合は、次のチェーンを使用して、より広範なロールからアクセス許可を継承します。

named-role → authenticated → anonymous

• エンティティ authenticated 構成されていない場合は、 anonymousから継承されます。
• 名前付きロールが構成されていない場合は、authenticatedから継承されるか、anonymousも存在しない場合はauthenticatedから継承されます。

つまり、 anonymous でアクセス許可を 1 回定義すると、すべての広範なロールが同じアクセス権を自動的に取得し、重複は必要ありません。

Example

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

この構成では、 anonymous、 authenticated、および構成されていない名前付きロールはすべて、 Bookを読み取ることができます。 継承が適用された後、 dab configure --show-effective-permissions を使用して、すべてのエンティティの解決済みアクセス許可を確認します。

アクション (string-array Permissions エンティティ名エンティティ)

関連付けられているロールに対して許可される操作の詳細を示す文字列配列。

* 現在、複数の操作は GraphQL でのみサポートされています。

Format

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

Example

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

代替形式 ( type=stored-procedureの場合は文字列のみ)

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

Example

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

アクション (object-array Permissions エンティティ名エンティティ)

関連付けられたロールに対して許可される操作の詳細を示すオブジェクト配列。

入れ子になったプロパティ

Format

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

Example

これによりreadフィールドとポリシーの制限を使用して、auditor エンティティにUserするアクセス許可が付与されます。

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

ポリシーに関する注意事項

データベース ポリシーは、OData スタイルの述語を使用してクエリ結果をフィルター処理します。 @item.<field>を使用してエンティティ フィールドを参照し、@claims.<type>認証されたユーザー要求を挿入します。

型 (GraphQL エンティティ名エンティティ)

GraphQL スキーマ内のエンティティの名前付け規則を設定します。

Format

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

入れ子になったプロパティ

* singular は、 type がオブジェクトとして指定されている場合に必要です。 typeがプレーン文字列の場合、その文字列は単数形の名前として使用されます。

Example

Configuration

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

GraphQL クエリ

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

GraphQL 応答

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

操作 (GraphQL エンティティ名エンティティ)

stored-procedureまたはQueryの下にMutation操作を表示するかどうかを指定します。

Format

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

例: operation

operationが に設定されている場合query

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

operationが に設定されている場合mutation

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

有効 (GraphQL エンティティ名エンティティ)

開発者が GraphQL スキーマにエンティティを選択的に含めることができます。

Format

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

REST (エンティティ名エンティティ)

* methods プロパティは、 stored-procedure エンドポイント専用です。

Format

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

説明 (エンティティ名エンティティ)

エンティティの人間が判読できる省略可能な説明。 この値は、生成された API ドキュメントと 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"
      }
    }
  }
}

フィールド (エンティティ名エンティティ)

エイリアス、説明、主キーの指定など、個々のデータベース フィールドのメタデータを定義します。 fields配列は、(mappings プロパティを介して) aliasと (source.key-fields プロパティを介して) primary-keyの両方を単一の統合された構造体に置き換えます。

入れ子になったプロパティ

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

この例では、 id を主キーとして指定します ( source.key-fieldsの必要性を置き換えます)。一方、 sku_title と sku_status は title と status ( mappingsの必要性に置き換えます)。

マッピング (エンティティ名エンティティ)

データベース オブジェクト フィールドのカスタム エイリアスまたは公開名を有効にします。

Format

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

Examples

データベース テーブル

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

Configuration

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

キャッシュ (エンティティ名エンティティ)

エンティティのキャッシュを有効にして構成します。

入れ子になったプロパティ

Format

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

level プロパティは、使用するキャッシュ層を制御します。

Example

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

リレーションシップ (エンティティ名エンティティ)

GraphQL エンティティを他の公開エンティティと関連付ける方法を構成します。 詳細については、「データ API ビルダーのリレーションシップの内訳を参照してください。

入れ子になったプロパティ

これらのプロパティは、リレーションシップのカーディナリティに応じて異なる組み合わせで使用されます。

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

例: 1 対 1 のカーディナリティ

各 Profile は正確に 1 つの Userに関連しており、各 User には 1 つの関連 Profileがあります。

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

GraphQL スキーマ

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

Command-line

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

例: 一対多カーディナリティ

Categoryには 1 つ以上の関連するBook エンティティを含めることができますが、各Bookには 1 つの関連するCategoryを含めることができます。

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

GraphQL スキーマ

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

コマンド ライン

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

例: 多対一カーディナリティ

多くの Book エンティティは、1 つの関連する Categoryを持つことができますが、 Category には 1 つ以上の関連する Book エントリを含めることができます。

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

GraphQL スキーマ

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

コマンド ライン

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

例: 多対多カーディナリティ

多くの Book エンティティには多くの関連 Author エンティティを含めることができますが、多くの Author エンティティには多くの関連する 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": {
        ...
      }
    }
  }
}

GraphQL スキーマ

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

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

コマンド ライン

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"

正常性 (エンティティ名エンティティ)

エンティティの正常性チェックを有効にして構成します。

入れ子になったプロパティ

Example

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

MCP (エンティティ名エンティティ)

エンティティの MCP 参加を制御します。 MCP がグローバルに有効になっている場合、エンティティは既定で参加します。 このプロパティを使用して、ストアド プロシージャ エンティティのカスタム MCP ツールをオプトアウトまたは有効にします。

オブジェクトの形式

詳細な制御には、オブジェクト形式を使用します。

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

カスタム ツール (ストアド プロシージャのみ)

ストアド プロシージャ エンティティの場合は、 custom-tool を true に設定して、プロシージャを名前付き MCP ツールとして登録します。

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

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