polygres-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polygres SDK

Build Python application code against the public

polygres-sdk

package and a project's Runtime API. Use

$polygres-cli

instead for human authentication, control-plane project administration, imports, migrations, and API-key management.

基于公开的

polygres-sdk

包和项目的Runtime API构建Python应用代码。对于人工身份验证、控制平面项目管理、导入、迁移及API密钥管理，请改用

$polygres-cli

。

Workflow

工作流程

Inspect
```
pyproject.toml
```
, requirements files, and existing client setup.
Confirm the installed
```
polygres-sdk
```
and
```
polygres-cli
```
versions before live or end-to-end testing. If testing a Polygres source checkout, create an isolated environment, reinstall both packages from that checkout under its dependency-installation policy, and verify their versions and import origins. Do not substitute PyPI packages for the checkout under test.
Outside a source checkout, compare both installed versions with the application requirements or current skill compatibility record. Obtain approval before installing or changing dependencies.
Resolve
```
POLYGRES_API_KEY
```
and
```
POLYGRES_RUNTIME_URL
```
from server-side environment configuration. Never log or embed either value.
Confirm that the URL is the per-project Runtime API URL, not the Polygres control-plane URL or a direct or pooled Postgres URL.
Resolve project mode before selecting a namespace. For a synced project, construct
```
client.project(project_mode="synced")
```
and read
```
references/synced-projects.md
```
.
Check
```
project.readiness()
```
before relying on graph, existing vector, or legacy hybrid retrieval. For new semantic retrieval, prefer Polygres AI Context: call
```
project.context.get_capabilities()
```
and then inspect collection status or verification. Use
```
project.connection_info()
```
only for passwordless connection metadata.
Keep every pgContext call on the flat
```
project.context
```
namespace. Prefer
```
$polygres-cli
```
for interactive setup. Use SDK mutations for explicit, backend-owned automation, return them immediately, and wait only when the application workflow requires a terminal result.
Choose one focused retrieval call. Use real row IDs returned by the SDK or verified application data; never invent graph identifiers.
Bound depth, candidate counts, result limits, pagination, and application token budget. Apply authorization before retrieval because filters are not an authorization boundary.
Preserve result provenance, request IDs, and typed models through RAG assembly. Deduplicate before constructing context.
Handle the documented exception hierarchy and test success, malformed responses, fuzzy or empty queries, invalid dimensions, and transient errors.

检查
```
pyproject.toml
```
、依赖文件及现有客户端设置。
在进行实时测试或端到端测试前，确认已安装的
```
polygres-sdk
```
和
```
polygres-cli
```
版本。如果测试的是Polygres源码检出版本，请创建隔离环境，根据其依赖安装策略从该检出版本重新安装这两个包，并验证它们的版本和导入来源。请勿用PyPI包替代待测试的检出版本。
在源码检出环境外，将已安装的两个版本与应用依赖或当前技能兼容性记录进行对比。安装或更改依赖前需获得批准。
从服务器端环境配置中获取
```
POLYGRES_API_KEY
```
和
```
POLYGRES_RUNTIME_URL
```
。切勿记录或嵌入这两个值。
确认该URL是每个项目的Runtime API URL，而非Polygres控制平面URL或直接/池化的Postgres URL。
在选择命名空间前确定项目模式。对于同步项目，构造
```
client.project(project_mode="synced")
```
并阅读
```
references/synced-projects.md
```
。
在依赖图检索、现有向量检索或传统混合检索前，检查
```
project.readiness()
```
。对于新的语义检索，优先使用Polygres AI Context：调用
```
project.context.get_capabilities()
```
，然后检查集合状态或验证情况。仅在获取无密码连接元数据时使用
```
project.connection_info()
```
。
所有pgContext调用均需使用扁平的
```
project.context
```
命名空间。交互式设置优先使用
```
$polygres-cli
```
。使用SDK变更操作进行明确的、后端主导的自动化处理，立即返回结果，仅当应用工作流需要最终结果时才等待。
选择一个聚焦的检索调用。使用SDK返回的真实行ID或已验证的应用数据；切勿自行编造图标识符。
限制深度、候选数、结果数量、分页及应用令牌预算。检索前先进行授权，因为过滤器并非授权边界。
在RAG组装过程中保留结果来源、请求ID及类型化模型。构建上下文前先进行去重。
处理文档中说明的异常层级，并测试成功响应、格式错误的响应、模糊或空查询、无效维度及临时错误。

Reference routing

参考路由

Read
```
references/client-setup.md
```
for installation, environment variables, endpoint selection, readiness, and passwordless connection information.
Read
```
references/synced-projects.md
```
for synced-project API-key limits, unavailable write and database surfaces, source-authoritative writes, and CLI or dashboard control-plane handoff.
Read
```
references/graph-retrieval.md
```
for graph calls, real row-ID discovery, direction, depth, and fan-out limits.
Read
```
references/vector-and-text.md
```
for existing vector compatibility, TSVector, fuzzy retrieval, filters, thresholds, and dimension checks.
Read
```
references/hybrid-and-rag.md
```
for graph-first, vector-first, joint retrieval, chaining, provenance, deduplication, and context budgets.
Read
```
references/context.md
```
for pgContext collection identity, multiple named vectors and defaults, explicit operations, point lifecycle, retrieval modes, and Joint versus rank fusion.
Read
```
references/rows.md
```
for validated single-row insert, upsert, ignore, retry, ambiguous-commit, and pipeline checkpoint behavior.
Read
```
references/errors-pagination-testing.md
```
for typed models, cursors, automatic pagination, exceptions, retries, and mocked tests.

阅读
```
references/client-setup.md
```
获取安装、环境变量、端点选择、就绪状态及无密码连接相关信息。
阅读
```
references/synced-projects.md
```
了解同步项目的API密钥限制、不可用的写入及数据库接口、源端主导的写入操作，以及CLI或控制台控制平面的交接方式。
阅读
```
references/graph-retrieval.md
```
获取图调用、真实行ID发现、方向、深度及扇出限制相关内容。
阅读
```
references/vector-and-text.md
```
了解现有向量兼容性、TSVector、模糊检索、过滤器、阈值及维度检查相关信息。
阅读
```
references/hybrid-and-rag.md
```
获取图优先、向量优先、联合检索、链式调用、来源追踪、去重及上下文预算相关内容。
阅读
```
references/context.md
```
了解pgContext集合标识、多个命名向量及默认值、显式操作、点生命周期、检索模式，以及联合检索与排序融合的区别。
阅读
```
references/rows.md
```
获取经过验证的单行插入、更新插入、忽略、重试、提交歧义及管道检查点行为相关内容。
阅读
```
references/errors-pagination-testing.md
```
了解类型化模型、游标、自动分页、异常、重试及模拟测试相关信息。

Boundaries

边界限制

Use only public SDK methods. Never reverse-engineer a private endpoint or private route, and never call the control-plane from application retrieval code.
Use
```
project.context
```
for backend-owned pgContext collection configuration. Activate
```
$polygres-cli
```
for interactive human workflows and control-plane work.
Use
```
project.vector
```
only with a previously registered, enabled configuration that is effectively Ready. HNSW requires its exact physical index to be Ready;
```
index_kind: none
```
can serve exact scan without HNSW. Do not infer a registration from a physical-only index or design new setup around vector-configuration creation; use
```
project.context.create_collection()
```
instead.
Do not pass pgvector configuration IDs to pgContext methods or imply that Polygres generates source or query embeddings.
Never print headers, environment variables, API keys, or database secrets.
Treat
```
connection_info()
```
as passwordless metadata. It does not return a database password. Never call it for a synced project.
Never use
```
project.rows
```
for a synced project or use rows validation as a capability probe. Mutate the source database instead.
Do not claim a query is authorized merely because it includes filters.
Do not retry validation, authentication, or permission errors blindly.
Do not hide partial pagination, malformed payloads, timeouts, or request IDs.

仅使用公开的SDK方法。切勿逆向工程私有端点或私有路由，且切勿从应用检索代码中调用控制平面。
使用
```
project.context
```
进行后端主导的pgContext集合配置。交互式人工工作流及控制平面工作请激活
```
$polygres-cli
```
。
仅在已注册且已启用的配置处于有效就绪状态时使用
```
project.vector
```
。HNSW要求其精确的物理索引处于就绪状态；
```
index_kind: none
```
可在无HNSW的情况下提供精确扫描服务。切勿从仅物理索引推断注册信息，或围绕向量配置创建设计新的设置；请改用
```
project.context.create_collection()
```
。
切勿将pgvector配置ID传递给pgContext方法，也不要暗示Polygres会生成源或查询嵌入向量。
切勿打印请求头、环境变量、API密钥或数据库密钥。
将
```
connection_info()
```
视为无密码元数据。它不会返回数据库密码。切勿为同步项目调用该方法。
切勿为同步项目使用
```
project.rows
```
，也不要将行验证用作功能探测。请改为修改源数据库。
切勿仅因查询包含过滤器就声称该查询已获授权。
切勿盲目重试验证、身份验证或权限错误。
切勿隐藏部分分页、格式错误的负载、超时或请求ID。

Completion report

完成报告

State project mode and the Runtime API context without secrets, retrieval strategy, filters and bounds, pagination behavior, provenance fields retained, tests run, and any readiness or configuration work still required through

$polygres-cli

说明项目模式及不含密钥的Runtime API上下文、检索策略、过滤器与限制、分页行为、保留的来源字段、已运行的测试，以及仍需通过

$polygres-cli

完成的就绪状态或配置工作。