統合カタログのエンティティフィールド値件数統計¶
POST /api/v1/unified_catalog/entity/field_value/count
概要¶
フィールドごとに、現在一致するエンティティの候補値と件数を統計します。
呼び出し前の準備と使用手順¶
fieldList は標準フィールドの同一性で重複排除し、最初に明示された表記を保持します。env と attributes.env は等価で、attributes.entityType とトップレベルの entityType は異なります。search は先にエンティティ集合を限定し、fieldValue はさらに候補バケットを絞り込むだけです。totalCount はエンティティの総数であり、バケット数ではありません。配列フィールドは値を分割するため、各バケットの件数の合計がエンティティ数と異なる場合があります。
すべてのエンティティタイプは有効なヘルス設定に従って処理され、バックエンドの履歴クリーンアップ進捗には依存しません。system でタイプポリシーが未設定の場合はデフォルトで default、その他のタイプで未設定の場合はデフォルトで disabled です。エンティティは inherit でタイプを継承し、custom で Func を指定し、disabled で無効化します。タイプが無効化されると、healthScore=null、healthStatus=unknown、healthUpdateAt=null を返し、ヘルスフィルタ/統計も履歴結果ではなく無効状態に従います。フィルタ/並べ替え/統計でトップレベルのヘルスフィールドを使用する場合は、entityType を明示する必要があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| providers[*] | string | 配列内の1つのソース。親配列を省略した場合はフィルタしません。 例: manual取得または入力方法: 既存エンティティの provider 値1つ。 |
|
| filters.属性フィールド名 | array または JSON | 動的キー。スカラーの候補値配列を推奨します。任意の DQL 式をフィールド名として扱うことはできません。urn/provider/entityType や healthStatus などのトップレベル組み込みフィールド、および snake_case の別名はトップレベルのままです。attributes/sourceMetadata/telemetrySelectors オブジェクト内のキーはフラット化されます。 例: ["prod"]取得または入力方法: 現在のエンティティの attributes にある実際のフィールド名を使用します。複雑な値のフィルタセマンティクスは、保存済みのフィールド型とクエリサービスの機能に依存します。 |
|
| filters.属性フィールド名[*] | JSON | 同一フィールドの候補値1つ。数値/ブール値は元の JSON 型を保持し、null と文字列の null を混同しないでください。 例: prod取得または入力方法: 現在のフィールド候補値/既存エンティティの値から取得します。 |
|
| fieldList[*] | string | 配列属性は複数の候補バケットに分割されます。ヘルスフィールドに関係する場合は entityType を必ず渡します。DQL ではなく、クエリサービスが認識できるフィールドを使用します。 例: attributes.env取得または入力方法: 単一のトップレベル/属性フィールド名。 |
|
| entityType | string | 一覧/統計では任意。トップレベルのヘルスフィールドでフィルタ、統計、または並べ替えを行う場合はビジネス上必須です。作成/変更では必須で、空白除去後に空でない必要があります。エクスポートでは必須です。 null を許可: False 例: database取得または入力方法: エンティティタイプ一覧の items[].entityType からコードを取得します。タイプ UUID/表示名ではありません。 |
|
| fieldList | array | Y | 1..64項目必須。空白項目はスキップし、同一標準フィールドの別名は重複排除します。有効な項目がない場合は406です。env 単体と attributes.env は同じフィールドで、attributes.entityType とトップレベルの entityType は異なります。 null を許可: False 最大長: 64 最小長: 1 例: ["provider", "attributes.env"]取得または入力方法: トポロジーフィールド一覧/既存タイプの属性から、統計対象のフィールドを取得します。 |
| fieldValue | string | 任意。空白除去後に空でない場合のみダウンストリームへ渡します。バケットのみを絞り込み、search のエンティティ集合への作用は変更しません。totalCount は引き続きエンティティのマッチ総数であり、候補キーワードによって縮小されません。 null を許可: False 例: prod取得または入力方法: ユーザーが入力する、絞り込み対象のフィールド候補値キーワード。 |
|
| filters | json | 任意のオブジェクト。{} は追加フィルタなし。属性キー env 単体は attributes.env に変換され、明示的な attributes.entityType はトップレベルの entityType として扱われません。複数の同一フィールド候補値は配列に入れ、異なるフィールドはクエリサービスに組み合わせを任せます。ヘルスフィールドには別途、実効的な無効状態があります。使用方法を参照してください。 null を許可: False 例: {"env": ["prod"]}取得または入力方法: フィールド名はタイプの DataSchema/属性またはトポロジーフィールド一覧 から取得し、値はフィールド統計/既存エンティティから取得します。 |
|
| provider | string | 任意。渡さない場合はソースでフィルタしません。複数ソースには providers を使用し、その非空値は provider より優先されます。エンティティのソースは変更されません。 null を許可: False 例: manual取得または入力方法: 既存エンティティの provider またはフィールド値統計の provider バケットから取得します。具体的な値は収集/報告元によって決まります。 |
|
| providers | array | 任意のソース配列。非空の場合は provider より優先されます。[] はソースフィルタを追加しません。空のソースだけを選択する意味ではありません。公開配列では項目ごとの文字列検証が宣言されていないため、実際の文字列のみを使用することを推奨します。 null を許可: False 例: ["manual"]取得または入力方法: field_value/count の provider に対する候補バケットから実際のソース値を取得します。 |
|
| search | string | 任意。省略/空文字列の場合はあいまい検索を行いません。エンティティ集合に作用し、fieldValue の候補値フィルタとは異なります。 null を許可: False 例: demo取得または入力方法: 呼び出し元がエンティティ名/URN/表示名に含まれる検索語を入力します。 |
|
| urn | string | 読み取り/削除では必須で、先頭と末尾の空白を除去した後に空でない必要があります。一覧/統計では任意の完全一致フィルタです。変更時は元の URN を明示的に入力し、名前変更時に別のエンティティが作成されるのを避けることを推奨します。 null を許可: False 例: urn:database:default:demo取得または入力方法: このワークスペースのエンティティ一覧 items[].urn から取得し、完全な URN をそのまま使用することを優先します。 |
パラメータ補足説明¶
リクエストパラメータの説明
| パラメータ名 | type | 必須 | 説明 |
|---|---|---|---|
| fieldList | array[string] | はい | 統計対象のフィールド一覧。最大 64 項目 |
| urn | string | いいえ | エンティティ URN による完全一致フィルタ |
| entityType | string | いいえ | エンティティタイプフィルタ |
| provider | string | いいえ | 単一のソースタイプ |
| providers | array[string] | いいえ | 複数のソースタイプ一覧 |
| search | string | いいえ | あいまい検索条件 |
| fieldValue | string | いいえ | 候補バケットのみを絞り込みます。search と同時に使用でき、それぞれエンティティ全体と候補値に作用します |
| filters | json | いいえ | attributes フィールドのフィルタ |
fieldList フィールドの説明
- エンティティの基本フィールドをサポートします。例:
entityType、provider、urn、name、displayName。 attributesフィールドをサポートします。例:env、project、attributes.env、attributes.project。envとattributes.envは等価です。
呼び出し時の注意事項
- レスポンスの
totalCountは、現在のフィルタ条件に一致したエンティティの総数を示し、fieldListの影響を受けません。 - 配列型の属性は複数の値に分割され、それぞれ統計されます。
fieldListまたはfiltersがヘルスフィールドに関係する場合はentityTypeを必ず渡します。タイプが disabled の場合はunknown/nullを実効的な無効状態として統計し、過去のヘルス値は読み取りません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/field_value/count' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"entityType":"database","fieldList":["provider","attributes.env"],"search":"demo","fieldValue":"","filters":{}}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.totalCount | integer | 一致するエンティティの総数。候補値キーワードの影響を受けません。 |
| content.items | array<object> | 重複排除された各フィールドの統計項目。 |
| content.items[].field | string | リクエストで最初に保持されたフィールド表記。 |
| content.items[].values | array<object> | 候補値バケット。一致しない場合は[]。 |
| content.items[].values[].value | JSON | フィールドの実際の値。null を許容します。無効化されたヘルスフィールドは有効値として統計されます。 |
| content.items[].values[].count | integer | この値に一致したエンティティ数。負ではありません。 |
| content.declaration | object | 共通宣言。 |
{
"code": 200,
"content": {
"totalCount": 1,
"items": [
{
"field": "provider",
"values": [
{
"value": "manual",
"count": 1
}
]
},
{
"field": "attributes.env",
"values": [
{
"value": "prod",
"count": 1
}
]
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
ダウンストリームエラーは Kodo の共通マッピングに従い、4xx は実際の HTTP と ft.KodoCommonApiErr またはマッピング済みのビジネスコードを返す場合があります。すべての失敗が 406 に変換されるわけではありません。透過されない 5xx/接続例外/成功結果の構造不一致は、最終的に 500 ft.InternalServerError になります。errorCode/message/traceId を保持し、読み取りまたは書き込み段階に応じて処理してください。HTTP の成功だけでは、エンティティが実際に可視であることの受け入れ確認の代わりにはなりません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | Body の最上位が JSON オブジェクトではない | 一部の json ファイルの形式エラー | 例に従ってオブジェクトを送信し、配列/文字列を使用しないでください。 |
| 406 | ft.InvalidParameter | 有効な fieldList がない、またはヘルス統計/フィルタに entityType がない | パラメータ {} が無効 |
1..64 個の有効なフィールドと対象タイプを送信してください。空文字列だけを入力しないでください。 |
| 500 | ft.InternalServerError | ダウンストリームクエリの失敗/タイムアウト、成功データの形状異常、またはタグ/チーム/時間のフォーマット失敗 | 内部エラー | クエリ範囲を狭めて適切に再試行してください。継続的に失敗する場合は traceId とフィルタ条件を保持して調査し、今回の書き込みに起因すると判断しないでください。 |