Back to Details

query

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rules for agents (read first)

Agent使用规则（请先阅读）

  • For a specific term you can name, use bounded 
    grep -C "term" file | head
    first     — it's leaner than ranked search.
  • Use query when grep would FLOOD, or when you have no reliable exact term: a common/ambiguous term over a corpus too large to scan (grep returns dozens of matches to sift), OR you don't know the document's exact wording (grep may return zero hits, sending you into repeated synonym guessing). query ranks the best passages and returns a bounded top-k, so it keeps context small.
  • Small 
    -k
    (1-2)     for a single fact; 
    --language <lang>
     for non-English so inflected/umlaut forms match (German 
    Antrag
    <->
    Anträge
    ).
  • Build an index (
    --emit-index
    ) only for many queries over the same corpus.
  • 若能明确指定术语，优先使用受限的
    grep -C "term" file | head
     —— 它比排序检索更高效。
  • 当grep返回结果过多，或无可靠精确术语时使用query： 比如在过大的语料库中搜索常见/模糊术语（grep返回数十个匹配项需逐一筛选），或者不清楚文档的确切表述（grep可能返回零结果，导致你反复尝试同义词）。query会对最相关的段落进行排序，并返回数量受限的前k个结果，因此能保持上下文范围可控。
  • 针对单一事实使用较小的
    -k
    值（1-2）    ；针对非英文文本使用
    --language <lang>
    参数，使变形词/带变音符号的词也能匹配（例如德语
    Antrag
    与
    Anträge
    ）。
  • 仅当需要对同一语料库进行多次查询时，才构建索引（
    --emit-index
    ）。

Query a document

文档查询

Ranked search over an already-extracted text or Markdown file. You give it a natural-language query; it returns the most relevant line windows (with line numbers), not the whole document. This is the "parse once, then query the file" pattern: convert a PDF a single time, then ask as many questions as you like against the cheap, local text.
This is built for agent economy. A converted document can be tens of thousands of lines and will blow out your context window if you read it back. Querying returns only the handful of passages that matter, with line numbers you can use for a precise follow-up read.
针对已提取的文本或Markdown文件进行排序检索。你输入自然语言查询，它会返回最相关的行窗口（带行号），而非整个文档。这是「解析一次，多次查询」的模式：将PDF转换一次，之后就可以针对本地的低成本文本随意提问。
该工具专为Agent经济性设计。转换后的文档可能有数万行内容，若直接读取会超出上下文窗口。查询仅返回少量关键段落，同时提供行号，你可借助行号进行精准的后续读取。

When to use this

使用场景

  • Use 
    query
     when you have a converted file and a question — "what's the termination clause", "where are the FY24 revenue figures", "does this mention indemnification". It ranks every line and hands back the best windows.
  • Use 
    pdf-to-markdown
    / 
    pdf-to-text
    first     to produce the file. 
    query
    does not parse PDFs; it searches their extracted text.
  • Don't read the whole converted file into context to find one thing, and don't run grep after grep — that's what this replaces. One ranked query beats many exact-match passes when you don't know the document's exact wording.
  • 当你有转换后的文件并需要提问时使用
    query
     —— 例如「终止条款是什么」「FY24营收数据在哪里」「文档中是否提及赔偿」。它会对每一行进行排序，并返回最优的内容窗口。
  • 先使用
    pdf-to-markdown
    / 
    pdf-to-text
    生成文件    。
    query
    不解析PDF，仅搜索已提取的文本。
  • 不要为了找一个内容而读取整个转换后的文件，也不要反复运行grep——这正是本工具要替代的操作。当你不清楚文档确切表述时，一次排序检索胜过多次精确匹配查询。

Related Nutrient skills

相关Nutrient技能

query
searches a file a converter already produced, so you'll usually want one of these too — add it the way your agent installs skills (they install separately but share the same underlying binary):
  • pdf-to-markdown
     — PDF → structured Markdown (headings, lists, tables); best for most RAG / LLM-context work.
  • pdf-to-text
     — PDF → layout-preserving plain text; best when column/tabular alignment must survive.
query
搜索转换器生成的文件，因此你通常还需要以下技能之一——按照Agent安装技能的方式添加即可（它们单独安装，但共享同一底层二进制文件）：
  • pdf-to-markdown
     —— 将PDF转换为结构化Markdown（包含标题、列表、表格）；最适合大多数RAG/LLM上下文场景。
  • pdf-to-text
     —— 将PDF转换为保留布局的纯文本；最适合需要保留列/表格对齐格式的场景。

Usage

使用方法

Before running any commands, set 
SKILL_DIR
to the absolute path of the directory containing this SKILL.md file. Use 
$SKILL_DIR/bin/query
in all commands below.
The 
$SKILL_DIR/bin/query
wrapper installs the platform-specific binary into 
~/.local/share/nutrient/cli/
from the CDN (cached; it only checks for updates every 6 hours). The same binary backs 
pdf-to-markdown
, 
pdf-to-text
, 
query
, and 
self-update
; installing any one of these skills gets you the same 
~/.local/share/nutrient/cli/
install — so once a PDF is converted you can search it with this skill.
bash
$SKILL_DIR/bin/query text INPUT.md "your natural-language query" [-k N] [-e N]
  • INPUT.md
    — the extracted text or Markdown file (the output of 
    pdf-to-markdown
    / 
    pdf-to-text
    ), or a prebuilt index (see below). The input type is auto-detected.
  • "query"
    — natural-language query, matched case-insensitively. Put several relevant terms in one query; BM-25 rewards rare, on-topic words, so a richer query ranks better.
  • -k N
    — maximum number of windows to return (default 8). Keep it small; you usually want the top 1–3.
  • -e N
    — context lines around each hit (default 5). Use 
    -e 0
    for just the matching line, or a larger value when you need more surrounding context.
Each result is a 
Lines A-B
window (1-based, inclusive) followed by those lines. Line numbers are global to the document, so you can 
Read INPUT.md
at that exact range for full context.
运行任何命令前，将
SKILL_DIR
设置为包含本SKILL.md文件的目录绝对路径。以下所有命令均使用
$SKILL_DIR/bin/query
。
$SKILL_DIR/bin/query
包装器会从CDN将平台特定的二进制文件安装到
~/.local/share/nutrient/cli/
（已缓存；每6小时检查一次更新）。同一二进制文件支持
pdf-to-markdown
、
pdf-to-text
、
query
和
self-update
；安装其中任何一个技能都会完成
~/.local/share/nutrient/cli/
的安装——因此PDF转换完成后，你即可使用本技能进行搜索。
bash
$SKILL_DIR/bin/query text INPUT.md "your natural-language query" [-k N] [-e N]
  • INPUT.md
    —— 已提取的文本或Markdown文件（
    pdf-to-markdown
    / 
    pdf-to-text
    的输出），或预构建的索引（见下文）。输入类型会自动检测。
  • "query"
    —— 自然语言查询，匹配时不区分大小写。在一个查询中包含多个相关术语；BM-25算法会对稀有且贴合主题的词给予更高权重，因此内容更丰富的查询排序结果更优。
  • -k N
    —— 返回的最大窗口数量（默认值为8）。请保持该值较小；通常你只需要前1–3个结果。
  • -e N
    —— 每个匹配结果周围的上下文行数（默认值为5）。使用
    -e 0
    仅返回匹配行，当需要更多上下文时可增大该值。
每个结果都是一个
Lines A-B
窗口（从1开始计数，包含首尾行），后面跟着对应行内容。行号是文档全局的，因此你可以在该精确范围内
Read INPUT.md
以获取完整上下文。

Reusing an index for repeated questions

为重复提问复用索引

If you'll ask several questions about the same document, build the index once and query that instead of rebuilding it every call:
bash
undefined
如果你需要对同一文档提出多个问题，可一次性构建索引，之后直接查询索引，无需每次调用都重新构建：
bash
undefined

First call: emit a reusable index alongside the answer.

首次调用：在返回答案的同时生成可复用索引。

$SKILL_DIR/bin/query text INPUT.md "first question" --emit-index INPUT.idx
$SKILL_DIR/bin/query text INPUT.md "first question" --emit-index INPUT.idx

Later calls: query the index — it's self-contained and skips the rebuild.

后续调用：查询索引——索引是自包含的，无需重新构建。

$SKILL_DIR/bin/query text INPUT.idx "second question" $SKILL_DIR/bin/query text INPUT.idx "third question"

The index is a self-describing file (it carries the document's lines), so `$SKILL_DIR/bin/query text INPUT.idx "..."` needs nothing else. The wrapper auto-detects whether you passed text or an index — same command either way.
$SKILL_DIR/bin/query text INPUT.idx "second question" $SKILL_DIR/bin/query text INPUT.idx "third question"

索引是自描述文件（包含文档的行内容），因此`$SKILL_DIR/bin/query text INPUT.idx "..."`无需其他文件。包装器会自动检测你传入的是文本还是索引——两种情况使用同一命令。

Workflow

工作流程

  1. Convert once: run 
    pdf-to-markdown
    or 
    pdf-to-text
    to produce 
    INPUT.md
    / 
    INPUT.txt
    . Do this a single time per document.
  2. Query, don't read: ask your question with 
    $SKILL_DIR/bin/query text INPUT.md "..."
    . Do not read the full converted file into context to answer — that's the cost this skill exists to avoid.
  3. Use the line numbers: the windows are usually enough to answer directly. If you need more, 
    Read INPUT.md
    at the reported 
    Lines A-B
    range — a targeted read, not the whole file.
  4. Don't waste time: for repeat questions on the same document, reuse the 
    --emit-index
    index (above) so each query skips the rebuild.
  5. Report concisely: answer from the returned windows. Don't paste the whole document back to the user.
  1. 转换一次：运行
    pdf-to-markdown
    或
    pdf-to-text
    生成
    INPUT.md
    / 
    INPUT.txt
    。每个文档仅需转换一次。
  2. 查询而非读取：使用
    $SKILL_DIR/bin/query text INPUT.md "..."
    提问。不要为了回答问题而读取整个转换后的文件——这正是本技能要避免的成本。
  3. 使用行号：返回的窗口通常足以直接回答问题。若需要更多内容，可在报告的
    Lines A-B
    范围内
    Read INPUT.md
    ——进行针对性读取，而非读取整个文件。
  4. 避免浪费时间：对同一文档重复提问时，复用
    --emit-index
    生成的索引（见上文），这样每次查询都无需重新构建索引。
  5. 简洁汇报：基于返回的窗口内容作答。不要将整个文档粘贴给用户。

Tips for good queries

优质查询技巧

  • Be specific and lexical. BM-25 is keyword ranking, not embeddings — it matches the words you give it. Use the terms you expect on the page ("indemnification", "net revenue", "effective date"), including synonyms, rather than a vague paraphrase.
  • One rich query beats many narrow ones. Stack the relevant terms into a single query instead of issuing several.
  • Adjust context with 
    -e
    , not by reading the file.     The default 
    -e 5
    already gives a generous window; raise it for more surrounding text, or drop to 
    -e 0
    for just the matching line. Only fall back to a full 
    Read
    at the reported range when you truly need the wider section.
  • Raise 
    -k
    only when you expect multiple distinct mentions.     For a single fact, 
    -k 1
    is enough.
  • 具体且用词精准。BM-25是关键词排序算法，而非嵌入模型——它匹配你输入的词汇。使用你预期会在文档中出现的术语（如「赔偿」「净收入」「生效日期」），包括同义词，而非模糊的转述。
  • 一次丰富查询胜过多次窄范围查询。将相关术语整合到一个查询中，而非多次发起查询。
  • 使用
    -e
    调整上下文，而非读取整个文件    。默认的
    -e 5
    已提供足够的上下文；需要更多周边文本时增大该值，仅需匹配行时可设为
    -e 0
    。仅当确实需要更广泛的内容时，才在报告的范围内进行完整
    Read
    操作。
  • 仅当预期存在多个不同提及内容时才增大
    -k
    值    。针对单一事实，
    -k 1
    足够。

Troubleshooting

故障排查

  • No relevant matches found
    (printed to stdout, exit 0)    : nothing ranked above the relevance threshold — the query words don't appear, or are too common. Try different/rarer terms, or 
    --mode lenient
    . This is a message, not document content; don't treat it as a result.
  • Truly empty output / no text to search: the converted file has no text (an image-only PDF converts to an empty file; 
    query
    searches text only and does not OCR). Re-check the 
    pdf-to-markdown
    / 
    pdf-to-text
    conversion before re-querying.
  • Hits look off-topic: the query was too generic, so common words dominated. Add rarer, more specific terms, or tighten with 
    --mode strict
    .
  • Inflected words missed (e.g. "terminate" vs "termination"): pass 
    --language en
    (or another ISO code) to enable stemming; the default is no stemming, exact word forms only. Run 
    $SKILL_DIR/bin/query --help
    for the full flag list.
  • Non-zero exit code: read stderr. Common causes — the input file doesn't exist, or (on the very first run) a network issue while downloading the binary.
  • First run is slow: the wrapper downloads the platform binary once (~a few seconds); later runs use the cache. Per-query cost after that is dominated by a one-time index build, which 
    --emit-index
    removes for subsequent calls.
  • No relevant matches found
    （输出到标准输出，退出码0）    ：没有结果超过相关性阈值——查询词汇未出现，或过于常见。尝试使用不同/更稀有的术语，或添加
    --mode lenient
    参数。这是提示信息，而非文档内容；不要将其视为结果。
  • 完全无输出/无文本可搜索：转换后的文件无文本内容（仅含图片的PDF转换后为空文件；
    query
    仅搜索文本，不支持OCR）。重新查询前，请检查
    pdf-to-markdown
    / 
    pdf-to-text
    的转换结果。
  • 匹配结果偏离主题：查询过于宽泛，导致常见词汇主导排序。添加更稀有、更具体的术语，或使用
    --mode strict
    参数收紧匹配规则。
  • 遗漏变形词（如「terminate」与「termination」）：传入
    --language en
    （或其他ISO代码）启用词干提取；默认不启用词干提取，仅匹配精确词形。运行
    $SKILL_DIR/bin/query --help
    查看完整参数列表。
  • 非零退出码：读取标准错误输出。常见原因——输入文件不存在，或（首次运行时）下载二进制文件时出现网络问题。
  • 首次运行缓慢：包装器会一次性下载平台二进制文件（约几秒）；后续运行会使用缓存。首次查询的耗时主要来自一次性索引构建，使用
    --emit-index
    可避免后续查询的索引构建步骤。

License

许可证

Free for processing up to 1,000 documents per calendar month. Each 
query
call is one processing event and counts as one document against that quota — the same as a 
pdf-to-markdown
/ 
pdf-to-text
conversion. The "parse once, query many" guidance saves your agent's context tokens and re-parse time, not the document quota (and an 
--emit-index
rebuild saved is time/CPU, not quota).
Commercial license required for:
  • processing over 1,000 documents/month
  • redistributing the binary
  • OEM/white-label use
Contact 
sales@nutrient.io
for commercial licensing.
每个日历月最多可免费处理1000份文档。每次
query
调用视为一次处理事件，计入文档配额——与
pdf-to-markdown
/ 
pdf-to-text
转换的计数规则相同。「解析一次，多次查询」的指导原则可节省Agent的上下文令牌和重复解析时间，但不节省文档配额（使用
--emit-index
避免重新构建索引节省的是时间/CPU，而非配额）。
以下场景需商业许可证：
  • 每月处理超过1000份文档
  • 分发二进制文件
  • OEM/白标使用
如需商业许可，请联系
sales@nutrient.io
。