POST /query

POST /api/signal-foundry/query は、agent が作った company_query.v1 を検証します。 実行可能な条件だけを Company Search に渡します。

自然文をこの endpoint に直接投げません。 Codex / Claude Code / 自社 backend 側で自然文を company_query.v1 に変換してから送ります。 unsupported / weak / needs_human は 0 件成功に変換せず、response の query.gaps と query.warnings を読んで復旧します。

契約サマリー

この endpoint の役割は、構造化された query plan を安全に実行することです。 Financial Gold や listing / corporate event executor で決定的な company_ids を作ります。 候補集合を交差してから、Company Search の company_ids filter として合成します。

Claude Code / Codex から使う場合は、まず company_query.v1 JSON を作り、CLI から実行します。自然文を sf search の q に残すと、財務閾値が未検証テキストとして扱われ、0 件成功のように見えることがあります。

sf query --file company-query.json --json

リクエスト

curl -s \
  -X POST \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  "https://signal-foundry.app/api/signal-foundry/query" \
  --data '{
    "contract_version": "company_query.v1",
    "raw_request": "上場企業の金融業界で売上1000億円以上",
    "predicates": [
      {
        "type": "listing_status",
        "operator": "in",
        "values": ["listed"]
      },
      {
        "type": "industry_33_code",
        "operator": "in",
        "values": ["7050", "7100", "7150", "7200"]
      },
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "revenue",
        "operator": "gte",
        "period": { "latest": true },
        "value": {
          "amount": 100000000000,
          "currency": "JPY",
          "unit": "absolute"
        }
      }
    ],
    "requested_output": {
      "limit": 20,
      "order": "name"
    },
    "execution_policy": {
      "allow_db_writes": false,
      "allow_external_search": false,
      "allow_llm_sql": false,
      "allow_unvalidated_q_fallback": false
    }
  }'

営業利益と純利益を含む複合条件では、canonical metric を使います。 operating_profit は operating_income、profit_margin は net_income_margin として alias warning 付きで実行します。 対応 metric と符号・派生の policy は、実行前に sf data capabilities --json の financial_metric_catalog で確認します。

sf query --json '{
    "contract_version": "company_query.v1",
    "raw_request": "上場企業で営業利益と純利益が黒字、かつ売上1000億円以上",
    "predicates": [
      {
        "type": "listing_status",
        "operator": "in",
        "values": ["listed"]
      },
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "operating_profit",
        "operator": "positive",
        "period": { "latest": true }
      },
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "net_income",
        "operator": "positive",
        "period": { "latest": true }
      },
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "revenue",
        "operator": "gte",
        "period": { "latest": true },
        "value": {
          "amount": 100000000000,
          "currency": "JPY",
          "unit": "absolute"
        }
      }
    ],
    "requested_output": {
      "limit": 5
    },
    "execution_policy": {
      "allow_db_writes": false,
      "allow_external_search": false,
      "allow_llm_sql": false,
      "allow_unvalidated_q_fallback": false
    }
  }'

Body

predicates[].type は次の値を受け付けます。実行条件を満たさない type や operator は、 query.gaps[] に開示して停止します。

数値コードは docs と実装のずれが起きにくいため推奨です。industry_33_code に 製造業 を渡すと16コードへ展開し、水産・農林業 は live code 50 と公式 code 0050 の両方へ展開します。日本語ラベルは trim 後の完全一致だけを受理します。 正規化した場合は query.gaps[] に industry_label_normalized を返すため、agent は 解釈したコードを利用者へ開示してください。

{
  "predicates": [
    { "type": "prefecture", "operator": "in", "values": ["大阪府"] },
    {
      "type": "industry_33_code",
      "operator": "in",
      "values": ["製造業"]
    },
    { "type": "employee_count", "operator": "gte", "value": 300 },
    { "type": "ai_jobs_presence", "operator": "eq", "value": true }
  ]
}

四半期 selector、前期比、QoQ の比較 predicate は未対応です。 quarter や trend_increase / trend_decrease を年次の latest に置き換えず、 unsupported_predicate または query.gaps[] で停止してください。

listing_event は、今年上場、2026年の新規上場、上場廃止、市場変更、社名変更、証券コード変更のような temporal event 条件に使います。 これは現在の listing_status=listed とは別条件です。代替してはいけません。

{
  "type": "listing_event",
  "operator": "match",
  "event_types": ["new_listing"],
  "date": {
    "gte": "2026-01-01",
    "lte": "2026-12-31"
  }
}

corporate_event は、合併、spin-off、会社分割、社名変更、証券コード変更など、participant role を持つ event に使います。

{
  "type": "corporate_event",
  "operator": "match",
  "event_types": ["merger"],
  "participant_roles": ["surviving_company"],
  "date": {
    "gte": "2026-01-01",
    "lte": "2026-12-31"
  }
}

会社名を含む event 検索では、identity_text を event predicate より先に解決します。 identity が 0 件なら company_identity_no_matches で止まり、全社の event を代わりに 返しません。

{
  "contract_version": "company_query.v1",
  "raw_request": "博展のTOB",
  "predicates": [
    {
      "type": "identity_text",
      "value": "博展",
      "confidence": 0.9
    },
    {
      "type": "corporate_event",
      "operator": "match",
      "event_types": ["tender_offer"]
    }
  ],
  "requested_output": { "limit": 20 }
}

POST /api/signal-foundry/query は、現役上場企業、現在上場企業、上場中の会社、 未上場企業、上場廃止企業 のような listing universe の語を自動変換しません。 この endpoint は company_query.v1 を検証し、受け取った predicate をそのまま実行します。 直接 API を使う場合は、listing_status predicate に listed、private、delisted の いずれかを明示してください。listing universe の語彙変換は event-search adapter 側の 処理であり、この endpoint の契約ではありません。

requested_output.limit は既定20、最大100です。event executor は同じ上限を使います。 match が上限を超える場合も matched_count はscan内で確認した母集団件数を保持し、 query.executors.company_events.result.truncated=true と query.gaps[].code="company_event_result_truncated" を返します。この gap の pagination_supported は false です。suggested_actions[] に従い、event type または date range を絞って再実行してください。

event 条件と Financial Gold 条件が混ざる場合は、 query.executors.company_events.result.company_ids と query.executors.financial_gold.result.company_ids を交差します。 全候補集合が非truncatedで交差が空の場合は company_query_candidate_intersection_empty で止めます。どちらかの集合が truncatedなら company_query_candidate_intersection_truncated で止め、真の空集合とは 断定しません。 片方の predicate を削って Search を走らせないでください。

会社を先に解決できている場合は、company_ids を top-level に入れます。 これにより、特定会社の財務確認や複数社比較の前段で、広い Financial Gold 条件が 全体 universe の上位 1000 件に丸められて false negative になることを避けます。

{
  "contract_version": "company_query.v1",
  "raw_request": "トヨタの営業CFが黒字か",
  "company_ids": ["jpx_7203"],
  "predicates": [
    {
      "type": "financial_metric",
      "source": "biz_1738_gold_financial_dataset",
      "metric": "operating_cash_flow",
      "operator": "positive",
      "period": { "latest": true }
    }
  ],
  "requested_output": { "limit": 5 }
}

Financial metric の正本は CLI が返す financial_metric_catalog です。agent は metric 名を選ぶ前に次を実行します。

sf data capabilities --json

見る key:

• financial_metric_catalog.metrics[]
• financial_metric_catalog.categories
• financial_metric_catalog.aliases[]
• financial_metric_catalog.compiler_hints[]
• financial_metric_catalog.unsupported_conditions[]
• financial_metric_catalog.unsupported_conditions[].agent_contract
• financial_metric_catalog.metrics[].policy.source_fact_filter
• financial_metric_catalog.metrics[].policy.guardrails
• financial_metric_catalog.metrics[].policy.component_formula
• financial_metric_catalog.metrics[].policy.derived_formula
• financial_metric_catalog.provenance_policy

financial_metric は現在、source: "biz_1738_gold_financial_dataset" の read-only 実行です。 実行可能な metric、alias、derived formula、component formula、unsupported 条件は financial_metric_catalog が正本です。 このページには全 metric 一覧を固定しません。CLI と docs がずれた場合は CLI の catalog を優先します。

自然文・短縮語は、agent が compiler_hints[] を読んで canonical metric に変換します。 これは schema alias ではありません。曖昧な現預金 / cash-equivalents の違いを判断できない場合は、 cash_and_cash_equivalents と cash_and_deposits のどちらを使うか確認します。

上位 / 下位 / 最大 / 最小 / top / bottom / highest / lowest のように ranking 軸が明確な場合は、 閾値を作らず requested_output.sort[] を使います。 direction: "desc" は上位 / 最大 / highest、direction: "asc" は下位 / 最小 / lowest です。 sort は 1 件だけ受け付け、tie-breaker は company_id 昇順です。

{
  "contract_version": "company_query.v1",
  "raw_request": "営業CFが大きい上場企業トップ20",
  "predicates": [
    {
      "type": "listing_status",
      "operator": "in",
      "values": ["listed"]
    }
  ],
  "requested_output": {
    "limit": 20,
    "sort": [
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "operating_cash_flow",
        "direction": "desc",
        "period": { "latest": true }
      }
    ]
  }
}

レスポンス

実行できた場合は company_query_result を返します。まず見る key:

• ok
• query.status
• query.executors.company_events.status
• query.executors.company_events.result.matched_events[]
• query.executors.financial_gold.status
• query.executors.financial_gold.result.ordering
• query.executors.financial_gold.result.matched_count
• query.executors.financial_gold.result.matched_financial_facts[]
• query.api.body.company_ids
• companies[].company.company_id
• companies[].matched_company_events[]
• companies[].matched_financial_facts[]
• companies[].financial_facts_period_alignment
• query.warnings[].code: "financial_metrics_period_mismatch"
• search.meta.returned_companies
• search.meta.total_kind
• search.meta.coverage_warnings

以下は短縮した例です。実際の query.executors.financial_gold.result.company_ids は最大 1000 件返ります。

{
  "object": "company_query_result",
  "ok": true,
  "status": "completed",
  "query": {
    "status": "supported",
    "execution": {
      "allowed": true,
      "reason": "validated"
    },
    "executors": {
      "company_events": {
        "status": "ready",
        "result": {
          "source": "hosted_table",
          "matched_count": 12,
          "company_ids": ["<company_id_1>", "<company_id_2>"],
          "matched_events": [
            {
              "company_id": "<company_id_1>",
              "event_family": "listing_event",
              "event_type": "new_listing",
              "event_date": "2026-04-01",
              "date_field": "listing_date",
              "event_id": "<listing_event_id>",
              "source": "jpx",
              "source_record_id": "<source_record_id>",
              "source_url": "<source_url>"
            }
          ],
          "truncated": false
        }
      },
      "financial_gold": {
        "status": "ready",
        "result": {
          "source": "hosted_table",
          "ordering": {
            "type": "financial_metric_value",
            "metric_id": "financial.revenue.latest_annual",
            "direction": "desc",
            "tie_breakers": ["company_id:asc"]
          },
          "matched_count": 968,
          "company_ids": ["<company_id_1>", "<company_id_2>"],
          "matched_financial_facts": [
            {
              "company_id": "<company_id_1>",
              "metric_id": "financial.revenue.latest_annual",
              "metric_key": "revenue",
              "value": 100000000000,
              "unit": "JPY",
              "period_end": "<period_end>",
              "filing_id": "<edinet_filing_id>",
              "source_id": "official_edinet",
              "source_key": "<source_fact_id>",
              "source_locator": "<source_locator>",
              "source_document_ref": {
                "source_table": "sf_edinet_filings",
                "source_doc_id": "<edinet_doc_id>",
                "source_filing_id": "<edinet_filing_id>"
              },
              "source_fact_ref": {
                "source_table": "sf_edinet_financial_facts",
                "source_fact_id": "<source_fact_id>",
                "source_locator": "<source_locator>"
              }
            }
          ],
          "truncated": false
        }
      }
    }
  },
  "companies": [
    {
      "company": {
        "company_id": "jpx_8306",
        "display_name": "三菱ＵＦＪフィナンシャル・グループ"
      }
    }
  ],
  "search": {
    "companies": [
      {
        "company": {
          "company_id": "jpx_8306",
          "display_name": "三菱ＵＦＪフィナンシャル・グループ"
        }
      }
    ],
    "meta": {
      "returned_companies": 20,
      "matched_companies": 62
    }
  }
}

companies は search.companies の convenience copy です。正本は search の Company Search response と query の validation result です。

search.meta.total_kind: "exact" は、company_ids を指定し、かつ free-text q を 併用しない確定集合だけで返ります。company_ids と q を併用した場合は、text match や truncation の影響を受けるため planner_estimate です。planner_estimate を母集団の 確定分母に使わないでください。総数を返さない場合は matched_companies: null と total_kind: "unknown" の組になります。

Event provenance の読み方

event 条件で会社が hit した理由を説明する場合は、query.executors.company_events.result.matched_events[] を読みます。

Gold value lineage の読み方

Financial Gold 条件で会社が hit した理由を説明する場合は、matched_count だけではなく query.executors.financial_gold.result.matched_financial_facts[] を読んでください。

Financial fact の period alignment

companies[].financial_facts_period_alignment は、同じ会社の matched_financial_facts[] が複数の対象期にまたがる場合に返ります。

{
  "aligned": false,
  "period_ends": ["2026-03-31", "unknown"]
}

unknown は、その fact の period_end が欠損していることを示します。日付のある fact と unknown が混在する場合は aligned: false とし、query.warnings[] に financial_metrics_period_mismatch を返します。全 fact が unknown の場合は比較不能であり、 期間不一致とは断定できないため、この field と warning は返しません。

aligned: false の場合は、そのまま指標を比較・rankingしないでください。 matched_financial_facts[] の period_end と filing evidence を確認し、同じ対象期の fact に 揃えてから再計算します。unknown を解消できない場合は、period gap として利用者へ残します。

0 件を判断するときは、先に query.gaps[]、query.warnings[]、 query.executors.company_events.status、query.executors.financial_gold.status を確認します。 各 executor が ready で、company_event_no_matches / financial_gold_no_matches / company_query_candidate_intersection_empty が返る場合は、どの集合で 0 件になったかを分けて説明します。 unsupported、hosted_table_pending、weak warning、*_result_truncated がある場合は、 市場不在ではなく capability / coverage / 実行境界として扱います。

実行不可 response

free cash flow / trend / short debt / long debt / unsupported generic ratio / search-data 行がない annual_YYYY selector / 財務条件の OR / NOT など実行できない条件の場合も、 可能な限り 200 で company_query を返します。 これを 0 件成功として扱わないでください。

{
  "object": "company_query",
  "ok": false,
  "status": "unsupported",
  "error": {
    "code": "financial_gold_adapter_unsupported",
    "message": "company_query.v1 could not be converted into an executable Company Search request."
  },
  "query": {
    "status": "unsupported",
    "gaps": [
      {
        "code": "financial_gold_adapter_unsupported",
        "severity": "blocking"
      }
    ]
  }
}

復旧方法

CLI equivalent

company_query.v1 は CLI から直接実行できます。 agent が自然文を受け取った場合は、自然文をこの command に直接渡さず、 先に company_query.v1 JSON を生成してください。

sf query --file company-query.json --json

財務閾値を正確に扱う workflow では、agent / backend が company_query.v1 を生成し、 この endpoint に送ります。 自然文のまま閾値を q に残すと、unsupported / weak 条件を 0 件成功と誤読しやすくなります。