pubfi-dsl-client

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PubFi DSL Client Guide

PubFi DSL 客户端指南

Overview

概述

This skill defines how to build safe, structured DSL requests for PubFi data access. The server only accepts structured DSL and executes a fixed OpenSearch query shape. The server does not accept SQL, raw OpenSearch DSL, or natural language compilation.

本技能定义了如何构建用于PubFi数据访问的安全、结构化DSL请求。服务器仅接受结构化DSL，并执行固定的OpenSearch查询格式。服务器不接受SQL、原始OpenSearch DSL或自然语言编译内容。

Base URL

基础URL

Set

API_BASE

to choose the environment:

Staging (publish target):
```
API_BASE=https://api-stg.pubfi.ai
```
Local debugging (Actix server):
```
API_BASE=http://127.0.0.1:23340
```

Note:

0.0.0.0

is typically a listen address, not a client address. If you still need it for local debugging, you may set

API_BASE=http://0.0.0.0:23340

设置

API_BASE

以选择环境：

预发布环境（发布目标）：
```
API_BASE=https://api-stg.pubfi.ai
```
本地调试（Actix服务器）：
```
API_BASE=http://127.0.0.1:23340
```

注意：

0.0.0.0

通常是监听地址，而非客户端地址。如果本地调试确实需要，可设置

API_BASE=http://0.0.0.0:23340

。

When To Use

使用场景

You need to convert an agent intent into a structured request.
You must avoid sending SQL or raw OpenSearch DSL to the server.
You need a deterministic, auditable query shape for billing and rate limits.

你需要将Agent的意图转换为结构化请求。
必须避免向服务器发送SQL或原始OpenSearch DSL。
需要用于计费和速率限制的确定性、可审计的查询格式。

Core Rules

核心规则

Only send fields defined in the DSL schema.
Do not send SQL, OpenSearch DSL, or arbitrary field names.
Use explicit UTC timestamps and treat
```
window.end
```
as exclusive.
Keep
```
search.doc_topk
```
, filter sizes, and aggregation sizes within the published limits from the schema endpoint.
Use
```
search.doc_topk = 0
```
when you only need aggregation results.

仅发送DSL schema中定义的字段。
不要发送SQL、OpenSearch DSL或任意字段名。
使用明确的UTC时间戳，并将
```
window.end
```
视为排他性时间。
确保
```
search.doc_topk
```
、过滤器大小和聚合大小符合schema端点公布的限制。
当仅需要聚合结果时，设置
```
search.doc_topk = 0
```
。

Workflow

工作流程

Fetch the schema from the API, or use
```
references/dsl-schema.md
```
as the local contract.
Convert the user intent into time window, filters, document fields, and aggregation primitives.
Validate the JSON shape and required fields before sending.
Record the request and response for audit and billing reconciliation.

从API获取schema，或使用本地契约文件
```
references/dsl-schema.md
```
。
将用户意图转换为时间窗口、过滤器、文档字段和聚合原语。
在发送前验证JSON格式和必填字段。
记录请求和响应，用于审计和账单对账。

Endpoints

端点

```
GET /v1/dsl/schema
```
```
POST /v1/dsl/query
```

```
GET /v1/dsl/schema
```
```
POST /v1/dsl/query
```

Example Commands

示例命令

Fetch the schema:

bash

curl -sS "$API_BASE/v1/dsl/schema"

Run a query:

bash

curl -sS "$API_BASE/v1/dsl/query" \
  -H 'content-type: application/json' \
  -d @request.json

获取schema：

bash

curl -sS "$API_BASE/v1/dsl/schema"

执行查询：

bash

curl -sS "$API_BASE/v1/dsl/query" \
  -H 'content-type: application/json' \
  -d @request.json

Example Request

示例请求

json

{
  "window": {"start": "2026-02-05T00:00:00Z", "end": "2026-02-06T00:00:00Z"},
  "search": {"text": "liquidity stress exchange withdrawal", "doc_topk": 50},
  "filters": {"tags": ["withdrawal_pause"], "entities": ["Binance"], "sources": ["coindesk"]},
  "output": {
    "fields": [
      "document_id",
      "title",
      "source",
      "source_published_at",
      "tag_slugs",
      "entity_labels",
      "document_summary"
    ],
    "aggregations": [
      {
        "name": "top_tags",
        "aggregation": {"type": "terms", "field": "tag_slugs", "size": 50, "min_doc_count": 2}
      },
      {
        "name": "volume_1h",
        "aggregation": {"type": "date_histogram", "field": "source_published_at", "fixed_interval": "1h"}
      },
      {
        "name": "tag_edges",
        "aggregation": {"type": "cooccurrence", "field": "tag_slugs", "outer_size": 50, "inner_size": 50, "min_doc_count": 2}
      }
    ]
  }
}

json

{
  "window": {"start": "2026-02-05T00:00:00Z", "end": "2026-02-06T00:00:00Z"},
  "search": {"text": "liquidity stress exchange withdrawal", "doc_topk": 50},
  "filters": {"tags": ["withdrawal_pause"], "entities": ["Binance"], "sources": ["coindesk"]},
  "output": {
    "fields": [
      "document_id",
      "title",
      "source",
      "source_published_at",
      "tag_slugs",
      "entity_labels",
      "document_summary"
    ],
    "aggregations": [
      {
        "name": "top_tags",
        "aggregation": {"type": "terms", "field": "tag_slugs", "size": 50, "min_doc_count": 2}
      },
      {
        "name": "volume_1h",
        "aggregation": {"type": "date_histogram", "field": "source_published_at", "fixed_interval": "1h"}
      },
      {
        "name": "tag_edges",
        "aggregation": {"type": "cooccurrence", "field": "tag_slugs", "outer_size": 50, "inner_size": 50, "min_doc_count": 2}
      }
    ]
  }
}

Common Mistakes

常见错误

Passing natural language constraints instead of structured filters.
Omitting
```
window
```
or using non-UTC timestamps.
Requesting too many fields or too many aggregations.
Using unsupported
```
fixed_interval
```
values.
Requesting large co-occurrence expansions that violate edge limits.

传递自然语言约束而非结构化过滤器。
遗漏
```
window
```
或使用非UTC时间戳。
请求过多字段或过多聚合。
使用不支持的
```
fixed_interval
```
值。
请求违反边缘限制的大型共现扩展。