クエリインサイト

クエリインサイトAPIを使用して、メタデータベースのクエリに一致する項目に対して集計インサイト (合計値、平均値、個数、その他) を計算することができます。まず、指定されたフィルタが適用された後で、指定されたグループ化条件に基づいて (指定していた場合) 集計が実行されます。インサイトを取得するには、POST https://api.box.com/2.0/query/insightsエンドポイントを呼び出します。

パラメータ

呼び出しを実行するには、次のパラメータを渡す必要があります。リクエスト本文には、queryおよびmetricsの2つのトップレベルフィールドがあります。必須のパラメータを太字で示しています。

パラメータ	型	説明	例
`query`	object	インサイトリクエストに対するフィルタ条件とグループ化パラメータを定義します。`predicate`、`params`、`ancestors`、`group_by`はそのまま維持してください (相互排他的なものではありません)。	`ancestors`
`query.predicate`	string	指標を計算する前に、データセットにフィルタを適用します。述語の構文はSQLの`WHERE`句と似ており、パラメータ化した引数を含めることができます。	`enterprise_12345678:book:amount >= :value`
`query.params`	object	各プレースホルダに対応するキーを含める必要があります。このキーは、プレースホルダの名前から`:`プレフィックスを取り除いた文字列と同じです。値のタイプが、述語で使用されているフィールドタイプと一致する必要があります。述語にパラメータプレースホルダが含まれる場合にのみ必要です (例: `:param`)。	`{ "value": 100 }`
`query.ancestors`	objectの配列	項目の先祖に基づいて、結果にフィルタを適用します。各オブジェクトに`id`および`type` (`folder`など) が必要です。指定した先祖のいずれかに含まれている項目が返されます。ユーザーは、指定したすべての先祖に対するアクセス権限を持っている必要があります。そうでない場合、リクエストが拒否されます。空にするか省略すると、アクセス可能なすべての項目を対象としてインサイトが計算されます (ルートコンテキスト、0)。	`[{ "id": "123", "type": "folder" }]`
`query.group_by`	objectの配列	データをグループ化する方法を指定します。各エントリでグループ化フィールドと、バケット制限 (オプション) が定義されます。現在サポートされているのは、1個のグループ化フィールドのみです。グループ化は、フィルタの適用後、指標の計算前に実行されます。濃度が高いフィールドを使用してグループ化するとエラーが発生する可能性があります。濃度が10,000未満になるようにしてください。
`[{ "field": "enterprise_12345678:book:category", "bucket_limit": 5 }]`
`query.group_by[].field`	string	グループ化に使用するフィールドの完全修飾フィールド名。サポートされるフィールドにはmetadataプロパティとitemプロパティが含まれます (サポートされるフィールドのタイプを参照してください)。	`enterprise_12345678:book:category`
`query.group_by[].bucket_limit`	integer	グループ化のために返されるバケットの最大数。デフォルト値は5、上限値は10です。	`5`
`metrics`	object (マップ)	計算する名前付き指標のセット。各エントリによって、ユーザーが定義したエイリアスが、フィールドに適用される指標操作にマッピングされます。指標はフィルタ処理の後 (加えて、グループ化が指定されている場合は、グループ化の後) で評価されます。1回のリクエストに最大10個の指標を含めることができます。	以降の例を参照してください。
`metrics.<alias>.type`	string	適用する集計機能。サポートされる値: `sum`、`avg`、`min`、`max`、`count`。	`count`
`metrics.<alias>.field`	string	指標計算の対象となるフィールドの完全修飾フィールド名。	`enterprise_12345678:product:category`

指標の名前

metricsオブジェクト内の各キーは、その指標に対してユーザーが定義したエイリアスです。 命名規則

空でない文字列にする
リクエスト内で一意であることが必要です
最大長さ: 256文字
使用可能な文字: アルファベット (a～z、A～Z)、数字 (0～9)、特殊文字_、-、.。
最初の文字を数字または特殊文字にしない
空白および他の特殊文字は使用できない

動作

group_byが指定されていない場合、指標はフィルタ適用後のデータセット全体を対象に計算されます (グループ化されない集計)。
metricsが空のオブジェクトである場合 ()、フィルタ適用後のデータセットに対してデフォルトのtotalResultCountカウント指標が返されます (ドキュメントの総数の例を参照してください)。

例

合計契約金額

2025年6月に作成された上位3つの契約タイプについて、合計契約額と合計契約数を取得します。 リクエスト:

{
    "query": {
      "predicate": "EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2",
      "params": {
        "templateArg": "enterprise_12345678:sales",
        "dateArg1": "2025-06-01T00:00:00-07:00",
        "dateArg2": "2025-07-01T00:00:00-07:00"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ],
      "group_by": [
        {
          "field": "enterprise_12345678:sales:contractType",
          "bucket_limit": 3
        }
      ]
    },
    "metrics": {
      "totalContractValue": {
        "type": "sum",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "countContractType": {
        "type": "count",
        "field": "enterprise_12345678:sales:contractType"
      }
    }
  }

レスポンス:

{
  "insights": [
    {
      "key": [ "ContractType1" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 180000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 245
          }
        }
      }
    },
    {
      "key": [ "ContractType4" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 100000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 185
          }
        }
      }
    },
    {
      "key": [ "ContractType2" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 200000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 150
          }
        }
      }
    },
    {
      "key": [],
      "type": "other",
      "metrics": {
        "totalCountBeyondTopGroups": {
          "type": "count",
          "values": {
            "count": 165
          }
        }
      }
    }
  ]
}

契約額の全体平均値、最低値、最大値

2025年6月に作成された契約について、契約額の全体平均値、最低値、最大値を取得します。 リクエスト:

{
    "query": {
      "predicate": "EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2",
      "params": {
        "templateArg": "enterprise_12345678:sales",
        "dateArg1": "2025-06-01T00:00:00-07:00",
        "dateArg2": "2025-07-01T00:00:00-07:00"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ]
    },
    "metrics": {
      "avgContractValue": {
        "type": "avg",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "minContractValue": {
        "type": "min",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "maxContractValue": {
        "type": "max",
        "field": "enterprise_12345678:sales:contractValue"
      }
    }
  }

レスポンス:

{
    "insights": [
      {
        "key": [],
        "type": "overall",
        "metrics": {
          "avgContractValue": {
            "type": "avg",
            "values": {
              "avg": 45055.50
            }
          },
          "minContractValue": {
            "type": "min",
            "values": {
              "min": 22000
            }
          },
          "maxContractValue": {
            "type": "max",
            "values": {
              "max": 75000
            }
          }
        }
      }
    ]
  }

ドキュメントの総数

空の指標オブジェクトを渡すことで、ドキュメントの総数のみを取得します。 リクエスト:

{
    "query": {
      "predicate": "EXISTS(:templateArg)",
      "params": {
        "templateArg": "enterprise_12345678:sales"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ]
    },
    "metrics": {}
  }

レスポンス:

{
    "insights": [
      {
        "key": [],
        "type": "overall",
        "metrics": {
          "totalResultCount": {
            "type": "count",
            "values": {
              "count": 12345
            }
          }
        }
      }
    ]
  }

レスポンスのフィールド

フィールド	型	説明	例
`insights`	array	リクエストの計算結果。各エントリは特定の結果タイプに対応し、関連付けられたグループ化キー (存在する場合) と計算された指標が含まれます。	以下を参照してください。
`insights.key`	objectの配列	このエントリをグループ化するためのキー値。構造はエントリのタイプによって異なります。	以下を参照してください。
`insights.key`	stringの配列	各`group_by`フィールドにつき1個の値。	`["Shoe"]`
`insights.type`	string	インサイトエントリのタイプ。`group`、`overall`、`other`のいずれかになります。	`group`
`insights.metrics`	object	指標の計算結果のマップ。各キーはユーザー定義の指標エイリアスです。それぞれの値に指標のタイプとその計算値が格納されています。その他のタイプのカウント指標は、`totalCountBeyondTopGroups`キーの中にあります。	`"metrics": {"totalPrice": {"type": "sum","values": {"sum": 50}}`

インサイトエントリタイプ

型	説明
`group`	`group_by`によって定義された、特定のグループの指標。`key`には、`group_by`フィールド1つにつき1個の値が含まれます。たとえば、カテゴリ = `"Shoe"`の場合の [“Shoe”] などです。
`overall`	データセット全体 (グループ化なし) に対して計算される指標。`key`は常に空の配列`[]`になります。
`other`	返された上位のグループに含まれない結果の集計数。空の配列`[]`は、上位の結果に含まれない、残りのすべてのグループを表します。

バケット順序

group_byによるリクエストについては、バケット順序は暗黙的に決まり、常に項目数 (各バケット内のドキュメント数) の降順となります。最大のバケットが最初に返されます。この順序はカスタマイズできません。 EnumフィールドとTaxonomyフィールドについては、削除ジョブの進行中に削除されたオプションが一時的に上位グループに表示される場合があります。こうしたグループは[DELETED]として示されるキーを持ちます。

エラーコード

以下の一覧に、APIが強化されたことで新たに導入できるようになったエラーコードと詳細の一部を示します。

エラーコード	エラータイプ	エラーメッセージ
`400`	`BAD_REQUEST`	[Expected JSON with type string. (文字列型のJSONを想定しています。)] または [Failed to parse query: Unexpected end of input. (クエリを解析できませんでした: 予期しない入力終了。)] メッセージ。クエリを解析できなかった場合、または想定していないJSONが渡された場合に返されます。
`401`	`UNAUTHORIZED`	[The access token provided is invalid. (指定されたアクセストークンは無効です。)]。使用されたアクセストークンが無効または期限が切れている場合に返されます。
`403`	`FORBIDDEN`	Query is restricted for this enterprise/scope. (この企業/スコープに対するクエリは制限されています。)
`404`	`INSTANCE_NOT_FOUND`	The templates you referenced were not found. (参照されているテンプレートが見つかりません。)
`429`	`RATE_LIMIT_EXCEEDED`	`EnterpriseId` is being rate limited. (EnterpriseIdはレートが制限されています。)
`500`	`INTERNAL_SERVER_ERROR`	Internal server error. (内部サーバーエラー。)

はじめに

アプリケーションと統合

IDとアクセス

APIの利用

トラブルシューティング

コンテンツ

コラボレーション

メタデータと検索

イベントとWebhook

ユーザー

インテリジェントなワークフロー

電子サイン

セキュリティとコンプライアンス

クエリインサイト

パラメータ

指標の名前

例

合計契約金額

契約額の全体平均値、最低値、最大値

ドキュメントの総数

レスポンスのフィールド

インサイトエントリタイプ

バケット順序

エラーコード

​パラメータ

​指標の名前

​例

​合計契約金額

​契約額の全体平均値、最低値、最大値

​ドキュメントの総数

​レスポンスのフィールド

​インサイトエントリタイプ

​バケット順序

​エラーコード

パラメータ

指標の名前

例

合計契約金額

契約額の全体平均値、最低値、最大値

ドキュメントの総数

レスポンスのフィールド

インサイトエントリタイプ

バケット順序

エラーコード