Python API 指南

使用公开的 purrdf 包。它的 Store、词项和查询结果与 Rust API 调用同一个原生引擎。通过 purrdf.shapes、purrdf.shex 和 purrdf.entail 导入验证与蕴涵功能。

完整签名参考 记录主包和 purrdf.geo 的权威 stub，包括属性、重载、命名空间别名和辅助类型。下文说明所有权、配置、结果解释和失败行为。签名中以下划线开头的类型描述实现或返回类型；列出这些类型并不意味着它们是公开构造器。例如，在注解中使用 purrdf.shapes.PreparedShapes，不要导入 _PreparedShapes。

TypedDict 声明描述字典结果的结构；不要假定每个结构名称都是导出的原生构造器。通过文档所述的生成方获取记录，再读取其命名字段。

加载与查询

Store.load(input, format, *, path, base) 接受文本、字节或由 path 指定的文件。必须提供且仅提供一个输入源，并指定格式。返回值是解析后文档的已解析前缀映射，按前缀排序；没有前缀声明的格式返回空映射。相对引用需要文档自身的基址声明或显式绝对 base。

import purrdf

store = purrdf.Store()
prefixes = store.load(
    '@prefix ex: <https://example.org/> . ex:alice ex:name "Alice" .',
    purrdf.RdfFormat.TURTLE,
)
assert prefixes == [("ex", "https://example.org/")]
rows = list(store.query(
    "SELECT ?name WHERE { <https://example.org/alice> "
    "<https://example.org/name> ?name }"
))
assert rows[0]["name"].value == "Alice"

SELECT 返回 QuerySolutions。结果行支持变量名、Variable 对象和整数位置，包括负索引。未绑定的投影单元格是 None，不会被省略。不存在的变量名引发 KeyError，越界位置引发 IndexError。ASK 返回 QueryBoolean。默认图上的 CONSTRUCT/DESCRIBE 结果迭代产生 Triple；携带命名图的结果迭代产生 Quad。

RDF 词项与精确值

NamedNode.value 是该节点的 IRI。Literal.value 保留词法形式；数据类型、语言和方向分别由其他属性表示。语言标签的身份比较忽略大小写。用 datatype=NamedNode(iri) 构造带数据类型的字面量，用 language= 构造语言字面量，同时指定 language= 和 direction= 构造带方向的语言字面量。

name = purrdf.NamedNode("https://example.org/alice")
text = purrdf.Literal("你好", language="zh-Hans")
assert name.value == "https://example.org/alice"
assert text.value == "你好"
assert text.language == "zh-Hans"

默认策略在商为有限小数时保留全部数字，否则舍入到小数点后 18 位，采用半偶舍入。division="exact" 将无限循环商作为表达式错误，使该单元格未绑定；division="N" 截断到小数点后 N 位，division="N:ROUNDING" 显式选择舍入方式。exact-or-N[:ROUNDING] 保留精确的有限商，只对循环商舍入。无效策略在执行前引发 ValueError。

result = store.query("SELECT ((1 / 1048576) AS ?value) {}")
assert list(result)[0]["value"].value == "0.00000095367431640625"
result = store.query("SELECT ((2 / 3) AS ?value) {}", division="2:half-even")
assert list(result)[0]["value"].value == "0.67"
xsd = "http://www.w3.org/2001/XMLSchema#"
assert purrdf.xsd_canonical_lexical("+00042", xsd + "integer") == "42"
assert purrdf.xsd_value_compare("1.00", xsd + "decimal", "1", xsd + "integer") == 0

result = store.query(
    'PREFIX xsd: <http://www.w3.org/2001/XMLSchema#> '
    'SELECT (xsd:dateTimeStamp("2024-02-29T12:30:00.123456789012345678901Z"'
    '^^xsd:dateTime) AS ?value) {}'
)
calendar = list(result)[0]["value"]
assert calendar.value == "2024-02-29T12:30:00.123456789012345678901Z"
assert calendar.datatype.value == xsd + "dateTimeStamp"

对于精确十进制数和时间值，应使用词法形式，不要先转换为 Python float 或小数位更少的表示。XSD 辅助函数对不支持的数据类型或格式错误的词法形式返回 None；若值空间无法为二者排序，例如涉及 NaN，比较也返回 None。

预备查询

用 Store.prepare(..., parameters=[...]) 声明参数名。每次运行都必须把每个已声明名称绑定到 RDF 词项。未知名称或缺失绑定会引发错误。配置在预备时固定，每次运行从存储读取源行。参数名不带 ?。

prepared = store.prepare(
    "SELECT ?name WHERE { ?person <https://example.org/name> ?name }",
    parameters=["person"],
)
assert prepared.parameters == ["person"]
rows = list(prepared.run(person=purrdf.NamedNode("https://example.org/alice")))
assert rows[0]["name"].value == "Alice"

资源治理与不完整答案

query_governed 在查询选项上增加 fuel、deadline_ms、max_answers、max_intermediate_cells、max_scratch_bytes、max_remote_requests、no_ceiling 和 cancel。上限包含边界值。省略上限仍保留计量。no_ceiling=True 关闭核算和资源上限，但保留截止期限与取消；它不能与显式上限同时使用。

stopped = store.query_governed("SELECT ?s ?p ?o WHERE { ?s ?p ?o }", fuel=0)
assert not stopped.is_complete
assert stopped.result is None
assert stopped.tripped is not None
complete = store.query_governed(
    "SELECT ?name WHERE { <https://example.org/alice> <https://example.org/name> ?name }")
assert complete.is_complete
assert list(complete.result)[0]["name"].value == "Alice"

只有 is_complete 为真时才有完整结果。发生中断时检查 tripped、partial 和 evidence，不要把部分答案当成全部结果。update_governed 返回自己的执行结果；中断的更新不应用任何修改。

命名图与引擎配置

默认 Store 记住已声明的空命名图。remember_empty_graphs=False 显式选择由行决定图存在性的另一模式。这些模式改变图是否存在，不改变已有 RDF 陈述的解释。

remembered = purrdf.Store()
remembered.update("CREATE GRAPH <https://example.org/empty>")
assert remembered.named_graphs() == [purrdf.NamedNode("https://example.org/empty")]
implicit = purrdf.Store(remember_empty_graphs=False)
implicit.update("CREATE GRAPH <https://example.org/empty>")
assert implicit.named_graphs() == []

查询、更新和预备入口接受显式扩展命名空间、属性函数命名空间、立场谓词、关系表、聚合命名空间、指定日期的 XPath 正则配置（profile）、地理配置和除法策略。依赖命名空间的扩展需要调用方提供配置。关系声明作为数据跨越边界，不是 Python 回调。

关系表、图内表与遍历

relations 将精确的谓词 IRI 映射到 (input_arity, output_arity, rows)。行包含原生 RDF 词项，展平后的宽度必须符合声明。relations_from_graph 提供列表头和相同的元数，从查询数据集读取表。path_relations 提供允许的谓词与方向步骤、最少和最多跳数、路径与展开限制，以及 walk 或 shortest。这些是数据声明，不是 Python 回调，因此求值可以释放 GIL。

遍历为每一跳输出一行，绑定端点、路径身份、长度、步骤、节点和经过的陈述。陈述是 RDF 1.2 三元组项，可以与普通图模式连接。每个遍历限制都必须显式指定；最少跳数为零、无效或重复步骤以及不可用的限制会引发 ValueError。有效路径若没有匹配边，则不贡献行。

可选证明声明为 (generation, incompleteness)，两者分别为字符串或 None，独立记录索引版本和宿主声明的数据不完整原因。None 表示没有声明，不是整个索引的完整性证明。受治理查询在 relation_witness 中返回这些声明；不受治理的调用无法报告已声明的缺失，因此拒绝该调用。三个关系映射之间重复注册、行宽不一致和破损 RDF 列表都是错误。已注册的精确 IRI 不需要命名空间设置；声明 property_fn_namespaces 后，这些前缀下未注册的 IRI 会成为硬错误，而不是普通图模式。

aggregate_namespace 注册十个内置统计聚合：MEDIAN、PERCENTILE、STDDEV、STDDEV_POP、VARIANCE、VAR_POP、MODE、FIRST、LAST 和 TOPK。它不注册任意 Python 累加器回调。xpath_regex 从 XPATH_REGEX_PROFILES 中选择规则；省略时保留兼容规则。模式或标志被拒绝属于表达式错误，原生 xpath-* 资源拒绝则引发 ValueError。standpoint_predicates 提供调用方的两个谓词 IRI；库不自行编造。

读取执行证据

CancellationToken.cancel() 是单调操作；检查 cancelled，并为另一段独立的取消生命周期创建新令牌。触发资源治理（governor）限制会返回执行结果，KeyboardInterrupt 则仍为异常。TrippedGovernor 提供 kind、label、dimension、limit、consumed、estimate 和 cause；准入估计不是实测消耗。

GovernorEvidence.consumed 和 limits 是按维度组织的映射，也可以通过 consumed_in() 和 limit_for() 读取。expression_errors 按完整限定 XPath 错误码统计已吸收的数值表达式错误，并保留零值条目。例如，投影中的除法错误可使单元格未绑定，但查询仍完成；COALESCE 可以恢复该错误。

PartialAnswers.certainty 区分 certain（每个返回行都是答案）、at-most（所有答案都包含在返回候选中）和 unknown（任何行都不可使用）。is_positional_prefix 是独立属性；可靠的子多重集未必是完整结果的前若干行。barrier 指明阻止认证的运算符。必须依据证书读取 result。UpdateOutcome.is_applied=False 表示没有发布任何修改。

始终存在的 QueryOutcome.relation_witness 将已调用关系 IRI 映射到调用次数、不同代次及声明的不完整原因。空映射不能证明完整性。调用次数反映执行调度，不能跨线程数或预算把它当作稳定索引身份比较。核算、优先级和区间保证见资源治理（governor）配置（profile）。

容器、修改与快照

load 和 bulk_load 返回文档最终已解析的前缀映射，不是陈述数量。add_graph 遵循构造器选择的图存在性模式；silent=True 抑制已存在的记忆图槽错误，不会抑制无效图名。named_graphs 排除默认图，并在存储记忆空图时包含已声明空槽。

批量加载后，Store.checkpoint() 将当前增量并入冻结基底，内容不变。随后 change_size() 报告该检查点之后的新增与删除。在增量验证序列前，应在加载完成后建立一次检查点，否则初始加载本身也属于待处理修改。压缩是显式工作，不应在每次单独修改后执行。

预备查询保留其来源存储，每次 run 都读取该存储的当前内容。从图派生的关系表与遍历会针对本次数据集重新构建，并重新进行计划准入。配置固定并不表示数据已冻结。PreparedQuery 不是线程安全的，运行尚未结束时不能重入。

查询在返回前物化拥有所有权的结果。QuerySolutions、QueryTriples 和 QueryQuads 是迭代器；以后还要遍历时应复制结果行。QuerySolutions.variables 提供有序结构。QueryQuads.graph_names 返回按 N-Triples 词项语法排序的图标记。将携带图的查询结果序列化为单图语法会引发 ValueError，不会默默擦除图名。四元组模板 CONSTRUCT 是本库扩展，不属于 SPARQL 1.2 的定义。

词项、格式与序列化

NamedNode 和 BlankNode 提供 value；Variable.value 是变量名。Triple 提供 subject、predicate 和 object；Quad 另有 graph_name。RDF 1.2 允许三元组项出现在宾语位置，不允许出现在主语位置。默认图由 DefaultGraph 表示，四元组构造器也接受 None 表示默认图。词项支持文档规定的相等比较和哈希；语言标签的相等比较忽略大小写，Literal.value 保留词法形式。普通字面量的数据类型读取值为 xsd:string；语言字面量和带方向的语言字面量分别返回 rdf:langString 和 rdf:dirLangString。

RdfFormat 成员为 TURTLE、N_TRIPLES、N_QUADS、TRIG、TRIX、HEXTUPLES、JSON_LD、YAML_LD 和 RDF_XML。文档自身的基址声明优先于传入的 base。相对引用若两者皆无，则引发带 iri-relative-no-base 的 ValueError；不会编造检索 IRI。输出时，不支持基址声明的格式使用绝对 IRI。

parse 返回四元组列表。serialize 和存储的 dump 重载向二进制输出写入字节；不传输出时返回字节。from_graph 选择导出图；base 选择输出基址，并与该选择组合。CompiledJsonLdContext 接受严格的选项 JSON，可以用 from_prefixes 构造，并提供可保留的 canonical_context_json。按声明传入支持的选项或已编译上下文；不要假定普通 Python 字典可以与 JSON 文本互换。

dump_with_loss 返回 SerializeLoss：包含 bytes，以及 statement_rows_dropped、directional_literals_dropped、named_graph_rows_dropped 和 empty_named_graphs_dropped。前三项按原因统计丢失的行或修饰信息；第四项统计只有声明而没有可计数行的图。应读取所有计数器。它们表示此次输出实际发生的损失，不同于 loss_matrix_json() 或 rdf_gts_loss_matrix_json() 返回的静态格式对矩阵。

to_json_ld、serialize_jsonld、from_json_ld、to_rdf_xml 和 from_rdf_xml 在 RDF 字节与文本形式之间转换。statement_vocab 是调用方显式提供的元数据词汇；其 class、subject、predicate、object 和 objectLiteral 值均为绝对 IRI。没有编造的命名空间后备。project_statements_rdf12 和 normalize_rdf12_to_owl 提供陈述编解码转换；canonicalize_turtle 返回规范字节，并可额外接收前缀映射。

Dataset.canonicalize 按 CanonicalizationAlgorithm.RDFC_1_0 或 UNSTABLE 原地重标记空节点。RdfDataset.to_nquads() 使用随库提供的平面规范化配置（profile）：它在 RDF 1.1 子集上与 RDFC-1.0 一致，而 RDF 1.2 配置有独立的保留词汇、陈述层和拒绝契约。不要将 RDF 1.2 摘要标为 RDFC-1.0。规范化拒绝会引发 ValueError。将字节用作身份前，请阅读规范化章节。

XSD 辅助函数接受词法字符串和数据类型 IRI：xsd_value_compare 返回顺序，遇到不支持、格式错误或无序值时返回 None；xsd_canonical_lexical、xsd_decode_binary 和 xsd_normalize_whitespace 返回其值或 None。不要先将精确十进制数或秒的小数部分转换为 Python float。

SPARQL 结果与来源记录

serialize_sparql_solutions 接受有序变量列表，以及每个变量对应一个单元格的行；未绑定单元格保留为 None。serialize_sparql_boolean 处理 ASK。两者按 SparqlResultsFormat 中的别名和媒体类型生成确定性的 JSON、XML、CSV 或 TSV 字节。parse_sparql_results 读取 JSON 或 XML，返回带区分标记的元组：("SELECT", variables, rows) 或 ("ASK", boolean)。这里没有 CSV 或 TSV 原生读取器。

来源记录是附加信息，需要 provenance_namespace=(prefix, iri)；query_hash 提供调用方的身份。provenance_from_json 和 provenance_from_xml 从该命名空间读回 query_hash 与 engine。没有来源记录时字段为 None，不会编造身份。

SHACL 验证、预备与规则

使用 purrdf.shapes；purrdf.shacl 是兼容别名。单次调用的 shapes.validate 接受 Turtle 形状和 N-Triples 数据，返回报告字典。shapes.Shapes 解析可复用形状。validate_nt 返回 ValidationReport；validate_store 直接读取 Store 或 MutableDataset 的原生快照，不经过文本往返。后续修改影响下一份报告，不改变已返回报告。

ValidationReport 提供 conforms、shapes_graph_well_formed、diagnostics 和 results，以及 to_ntriples() 和 to_sarif()。结果消息保留文本、语言、方向和数据类型。空 sh:in 或 sh:xone 列表会在结果之外生成强制诊断，但不改变符合性或报告图。单次调用报告记录 conformance_disallows：省略时使用 SHACL 默认的 Violation/Warning/Info 集合，不含 Debug 和 Trace。禁止集合为空或严重性不是 IRI 时会引发异常。

shapes_ttl = '''
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix ex: <https://example.org/> .
ex:PersonShape a sh:NodeShape;
    sh:targetNode ex:alice;
    sh:property [ sh:path ex:name; sh:minCount 1 ] .
'''
shapes = purrdf.shapes.Shapes(shapes_ttl)
assert shapes.validate_store(store).conforms
prepared_shapes = shapes.prepare()
product = purrdf.shapes.ShapesProduct.open(prepared_shapes.to_product())
restored = product.admit_expecting(product.identity_digest())
assert restored.validate_nt(
    '<https://example.org/alice> <https://example.org/name> "Alice" .'
).conforms

导入与执行环境

每个形状入口从调用方提供的有序 imports 表解析导入，条目为 (IRI, Turtle document)。它不获取网络内容。未解析或无效导入、未使用条目及不兼容版本会引发 shapes.ShapesImportError；按 kind 分支并检查 iris。数据图中的 sh:shapesGraph 链接必须由手头材料解析。预备形状不能在数据到达时默默加入另一个链接图；未持有的链接会被拒绝。

shapes_base（或 Shapes(..., base=...)）解析相对形状 IRI。shapes_graph 命名 SHACL-SPARQL 通过 $shapesGraph 读取的图；省略时不编造图。这是 SHACL 1.0 的预绑定，已从 SHACL 1.2 移除。subclass_of_in_shapes_graph=True 还会读取形状图中的子类三元组判断类成员；rdf:type 仍来自数据图。xpath_regex 将指定日期的规则用于分面和嵌入式 SPARQL。资源拒绝会引发异常，不会返回空报告或符合报告。

Shapes.extension_usage 在验证前检查声明：sites 按给定命名空间和注册项区分调用与数据谓词；unreadable 和 complete 表明准入失败。因此可以区分未识别关系与没有结果行的有效关系。shapes.lint_shapes 执行冷审计，报告发现、加载错误、强制诊断、已被取代的验证器、未执行的查询声明、导入锚定和确定性报告文本。两者都不是数据验证。

预备产物与增量报告

Shapes.prepare() 返回 PreparedShapes；to_product() 写入确定性字节。shapes.pack_product() 组合解析、准备和写入。ShapesProduct.open() 验证封装并读取自描述信息，但不准入可执行预备结果。检查 format_version、stage_id、stage_known、identity_digest、identity_components 和 explain；to_bytes 返回封装。admit 恢复已知阶段，rebuild 在需要时重建。它们的 _expecting 形式绑定预期身份，并以维度 shapes-graph 拒绝不匹配。certify 检查产物的认证义务。应按 ShapesProductError.dimension 分支，不解析异常文本。PreparedShapes.provenance() 区分已解析、恢复后准入和恢复后重建的预备结果。

PreparedShapes.validate_store_changes(store) 返回 ChangeValidation。读取 report.conforms 前先检查 bounded：为真时，报告仅覆盖受影响焦点节点，不对无法到达的旧违规作出断言；为假时，报告覆盖修改后图的完整验证。受限分支的 focus_nodes 为计数，否则为 None；reason 标识需要完整运行的构造。待处理修改由调用方上一次 checkpoint 决定；验证不重新定义该检查点。

规则与节点表达式

shapes.entail 应用形状图的默认规则集，返回基底与推导三元组。它不同于 purrdf.entail.materialize，后者使用蕴涵机制的规则表，不需要形状图。shapes.apply_rules 运行 SRL 文档，仅返回推理图；explain=True 时另有证明文本。check_rules 按所选检查级别准入规则集：level 接受 syntax、well-formed 或 stratified；省略时选择 stratified。它报告声明、导入、版本和分层。存储事实数、连接步数、生成词项数和生成轮数均由显式关键字参数限制；耗尽时引发对应限制的 ValueError。

eval_node_expr 必须恰好选择一个表达式：具名 IRI 或空节点标签，从 expr_at 经 expr_via 的唯一遍历，或只有一个根的内联 expr_turtle 文档。focus 和 scope 提供词项；保留的 focusNode 不能重新绑定。选择器有歧义、遍历步骤缺失或多值以及求值失败都会引发异常。输出为有序 N-Triples 词项字符串，并附有强制诊断。完整契约见 SHACL 与预备产物。

ShEx

purrdf.shex.parse 将 ShExC 或 ShExJ 转换为规范 ShExJ 文本。shex.validate 接受模式、数据和固定形状映射。每个 (node, shape) 对会在 ShexResultEntry 中原样返回，并附有 conformant 和可选 reason。节点可为裸 IRI、尖括号 IRI、_: 标签或 Turtle 字面量标记；START 选择起始形状。模式格式为 shexc 和 shexj；数据格式为 turtle、ntriples 和 nquads。base 解析两个输入中的相对 IRI。被所选 XPath 规则拒绝的模式使该条目不符合；原生资源拒绝则对整个映射引发异常。参见 ShEx。

蕴涵、判定与证明

purrdf.entail.Regime 包含 SIMPLE、RDF、RDFS、OWL_RL、OWL_DIRECT、RIF 和 D；函数也接受命令行的小写拼写。未知拼写会引发异常。materialize 返回 (RdfDataset, report)，materialize_nt 返回 (canonical_text, report)；报告始终存在。program 为 RIF 文档，其他机制必须传空值。必需的 imports 和 premise_iris 描述前提的导入闭包；[] 表示没有。非绝对前提 IRI、未解析导入和不可达表条目会引发异常，不会被获取或忽略。rules、implemented_rules 和 extensions 分别提供规范规则表、已实现子集和具名非规范扩展。

chase 报告描述规则覆盖情况；OWL Direct-Semantics 服务返回判定证书。规则表不完整与判定耗尽工作上限是两回事。应解包证书并与答案一起保留。

step_cap 和 work_cap 只能收紧判定引擎推导的上限；零表示选择引擎自身的上限，不是零工作。证书报告轮数、工作量、判定次数、峰值节点数、分支次数和深度。预算耗尽为 unknown，不是否定定理。除 consistency 外，判定服务拒绝没有模型的本体，不会把空真蕴涵作为普通答案。未提及的类可以返回空实例答案，不必报错。

entail.Reasoner 保留已解析数据，按需惰性构建知识库，并在对应服务方法间复用两者。上限在构造时固定。proofs=True 启用轨迹，records_proofs 报告该选择。prove 返回答案、证书和证明；proof_services 列出支持的服务名。不记录证明的会话会拒绝证明请求。check_proof 针对调用方的本体、问题、答案和证书检查；未记录的证明绝不会通过验证。空答案或空证书请求较弱的检查，报告会明确说明。论证与执行证明回答不同问题。

certain_answers 查询在所有模型中成立的替换，不只是某个闭包中的匹配。谓词变量及三元组项中的变量可绑定；空节点不是区分变量。应阅读 limit 行以识别未穷尽边界。graph_entails 查询结论图，明确区分蕴涵、不蕴涵和未判定。verify_entailment 根据原样前提复查现有蕴涵证据（warrant）。这些调用要求导入和前提 IRI，并拒绝签名无法表达所需输入的机制。字面量数据类型位置上的变量会被拒绝。

Store.query_entailment_governed 有两个阶段。闭包构建停止时，产生 EntailmentQueryOutcome.phase == "closure-stopped"，没有查询结果或闭包报告。否则阶段为 answered，带普通的受治理查询结果和报告。图内关系读取闭包。若 OWL Direct 闭包通过遍历暴露生成的存在见证，则以 reasoning-closure-relation-witness 拒绝。完整服务与证书语法见蕴涵。

地理会话

purrdf.geo.GeoProfile 拥有不可变的严格地理配置；to_json 返回含显式限制的规范版本一记录。GeoSession 接受该配置、另一个会话、配置 JSON 或 None；省略时选择标准 CRS84 配置。profile() 返回所选配置。查询、更新和预备方法通过 geo 接受相同选择。

GeoSession.call 求值严格的标量或批量 JSON 请求；point_index 构建不可变原生点桶并返回 GeoPointIndex，其 call 用相同比较规则精化搜索。语义结果保持规范 JSON；操作性拒绝引发 ValueError。这些路径使用共享 Rust 编解码器，没有 Python 几何实现。参见 GeoSPARQL。

GTS 容器与不可变数据集

GTS 函数既可从包根访问，也归组在 purrdf.gts 中；命名空间别名引用相同操作和类型。gts_from_quads 和 gts_from_rdf12_bytes 按请求的 profile、transform 和 base 将 RDF 字节摄入快照。snapshot_content_id_native 读取对应快照身份。

compile_gts_native 接受基底文档、可选 RDF 1.2 层、命名图及其作用域、文档或报告 blob 和切片产物。签名输入与 rsyncable 阈值是显式编译参数。blob 行携带字节、媒体类型和表示；切片产物行还包含切片 IRI、名称、角色和逻辑路径。必须保留声明的元组位置，不能根据最后一项的类型猜测。

compile_gts_with_report 返回 GtsCompileResult，将 snapshot_bytes 与同一次解析和驻留操作的摄入回执配对。gts_ingest_report 只读取回执。GtsIngestReport 记录 rows_consumed、terms_interned、declarations_omitted 和 scratch_bytes。只有声明的命名图在冻结分发载荷中没有行；其 IRI 会报告为已省略，而不是被静默驻留后改变快照身份。空四元组表不能证明没有丢失声明。feedback_bundle_native 将报告 blob 附加到所提供的 RDF 输入。

RdfDataset 拥有冻结的已解析数据集。其 quad_count、term_count 和长度是检查方法。to_nquads 提供上文所述的规范平面文本；serialize_jsonld 支持声明的 JSON-LD/YAML-LD 选项和已编译上下文。to_gts、columnar_rows 和 to_parquet_files 导出同一个原生载体。字典的数值词项标识符只属于该所有者；跨独立数据集时应解析词项。

frozen = purrdf.RdfDataset(
    '<https://example.org/alice> <https://example.org/name> "Alice" .',
    purrdf.RdfFormat.N_TRIPLES,
)
container = frozen.to_gts()
view = purrdf.GtsFoldViewNative.from_bytes(container)
assert view.quad_count() == 1
alice_id = view.tid_of_iri("https://example.org/alice")
assert alice_id is not None
assert view.public_text(alice_id, "https://example.org/name") == "Alice"

折叠视图与语言选择

GtsFoldViewNative.from_bytes 读取容器；from_parts 准入调用方提供的词项、四元组、具体化节点（reifier）和注解表。两者都以 gts-self-reaching-term 拒绝能够到达自身的词项，不会暴露无限递归的渲染器。curie_prefixes 提供宿主的 CURIE 映射；只有文档列出的 W3C 命名空间是内置的。

四个计数方法报告表大小。term_tuple、is_iri、is_bnode、is_literal、iri、lex、lang、datatype、nq_token 和 python_value 检查本地词项；tid_of_iri 执行反向查找，curie 缩写 IRI。quads、subjects_by_type、objects、value、predicate_objects、has 和 rdf_list 查询所选 scope。reifiers 和 annotations 返回各自的陈述层表。不要把其中的整数 ID 与另一个独立构建视图的 ID 比较。

省略作用域或传 None 时选择默认图。purrdf.GTS_ALL_SCOPE 选择所有图；命名图 IRI 选择该图，未知 IRI 没有匹配行。全图哨兵不是命名图 IRI。

tag_map 和 available_languages 提供视图中的语言选择。public_text 和 public_literal 选择公开值；_with_fallback 形式还接受请求语言，并报告是否使用后备值。public_texts 返回请求的多个选择及该元数据。如果展示依赖于所请求译文是否实际存在，应保留语言和后备字段。

关系式与 Parquet 导出

relational_rows 和 gts_relational_rows_from_bytes 返回 GtsRelationalRows：词项、四元组、具体化节点、注解和 blob；其中 directions 数组与 terms 按位置对应。方向不是附加在位置词项元组末尾的新字段。ColumnarRows 则携带原生 v1 结构和投影后的五表行，其按值排序的稠密标识符不必等于原始 GTS ID。

gts_columnar_rows_from_bytes 返回该投影；gts_columnar_parquet_from_bytes 和 RdfDataset.to_parquet_files 返回文件名到字节的映射。gts_to_sqlite、gts_to_duckdb 和 gts_to_parquet 将五表投影写到指定目标。SQLite 使用标准库，DuckDB 需要其可选依赖组，Parquet 写入使用原生编解码器；PyArrow 是互操作读取器，不是写出器。参见 GTS 与列式配置（profile）。

图与表格投影包

project 接受 RDF 文本或字节、对应 RdfFormat、显式 ProjectionProfile 和严格配置 JSON，返回含所选 profile、确定性 USTAR archive 和结构化 losses 的 ProjectionPackage。每个 ProjectionLoss 包含 code、source、target、note 和可选 location；应检查记录，不要假定每种配置都能往返。可选 assets 输入属于包配置。

配置（profile）为 lpg-csv、neo4j-csv、open-cypher、graphml、csvw-exact、csvw-terms、okf-terms、obo-graphs、skos、croissant-1.1、ro-crate-1.3、datacite-4.6、dcat-3、dcat-rdf、void 和 frictionless-data-package-1。lift 支持 LiftProfile 子集，返回 ProjectionLift.dataset 和损失；把单向配置名传给 lift 不会使它变成双向配置。

流式 LPG 产物通过 project_artifacts 以 (event, path, chunk) 调用产物回调。ArtifactEvent 值界定生命周期：begin-package、begin-artifact、chunk、finish-artifact、commit-package 和 abort-package。只有提交后才能发布保留的产物，并且必须处理中止。可选进度回调接收不可变 ProjectionProgress 快照，包含阶段及节点、边、产物和字节计数。返回的 ProjectionStream 报告配置（profile）与损失。这些是显式产物回调，不同于只接受数据的 SPARQL 关系声明。各配置的严格设置和往返契约见投影。

SSSOM 映射文档

validate_sssom 返回 SssomDiagnostic 字典，包含严重性、错误码、消息、检查项和可选实例。无问题文档返回 []；解析失败返回检查项为 parse 的 FATAL 诊断，不是成功的空验证。sssom_to_rdf 从 TSV 生成 RDF；sssom_roundtrip_tsv 写出已解析的映射文档，sssom_default_validation_types 提供原生默认验证类型。这些是原生 SSSOM 编解码功能，不会导入外部 sssom 包。

切片目录与所有权

purrdf.slice.SliceCatalog.discover(root, namespace) 使用调用方命名空间读取清单。records 包含带清单、清单路径、切片目录和产物记录列表的 SliceRecord 值；core_slice_iris 报告核心成员。ManifestView 提供标识符、切片 IRI、标签、标题、层级、创建者和使用者。ArtifactRecord 提供角色、逻辑路径、媒体类型、原始摘要、语义摘要和内容。

fix_deps() 返回含原始文本和建议文本的 ManifestPatch；调用方决定何时写入这些补丁。OwnershipAnalyzer 在构造时立即执行分析；analyze() 返回保留的 OwnershipReport，analysis_graph_turtle() 序列化分析图。报告提供所有权错误、缺陷标志，以及含来源、目标、语义或物理状态和声明核对结果的 DependencyEdge。这是清单与产物所有权，不是根据目录名推断。参见切片。

排序检索与精确融合

purrdf.retrieval 提供 plan、compile 和 search，以及冷文档检查和融合规则设计查询。plan 不执行查询，只记录规范请求、各分层深度、查询过的统计、生成方决策和未服务词项。compile 准入该计划并生成各分层 SPARQL。search 执行完整的计划、编译、执行和融合流程。Python 没有分别暴露 execute 与 fuse 的流句柄入口。

文本生成方将生成方 IRI 映射到 (stratum, predicate, graph, analyzer)。分析器必须选择 lexicon，并按需要声明文档规定的词典产物或条目、标量限制、重音、词干、输入与投影模式以及子串预算。图选择器为 any、default 或命名图 IRI。可选尾部位置依次为域、索引证明声明和搜索保真度；元组宽度有歧义或不受支持时引发异常。索引证明声明为 (generation, incompleteness)，保真度为 (completeness, order)；二者描述不同事实。

knn_producers 和 hnsw_producers 在调用方提供的 (IRI, vector) 行上注册精确扫描和近似图搜索，以实体请求作为种子。向量须具有相同的有限宽度和唯一有效 IRI；余弦拒绝零向量。候选与邻居限制均须显式指定且为正。生成方度量为 cosine、negative_dot 和 squared_euclidean。HNSW 还声明 (m, m0, ef_construction, ef_search)，并验证 m >= 2、m0 >= m、ef_construction >= m0 和 ef_search >= 1。三个映射不能重复注册生成方 IRI 或分层。调用方还提供统计的 source 与 revision；基数和以百万分比整数表示的选择率是可选的。未知测量值为 None，不是零。

请求是带类型元组的序列；生成方适用性由计划阶段报告，因此写出请求类型并不会为它自动创建生成方。

候选域要么不受限（None），要么只有一个不同的宿主域标签。空标签或多个不同标签会被拒绝；同一标签的多次重复仍表示一个域。域声明授权排除操作，因此生成方若把某个候选列在不相交域中，就属于错误；不能在分数认证后默默扩大声明。唯一流中重复的候选也会被拒绝。

retrieval = purrdf.retrieval
notes = '''
<https://example.org/a> <https://example.org/note> "the quick brown fox" .
<https://example.org/b> <https://example.org/note> "a quick red fox" .
'''
ranking = retrieval.search(
    notes,
    [("lexical", "quick fox", None, "https://example.org/note")],
    text_producers={
        "https://example.org/pf/search": (
            "https://example.org/stratum/lexical",
            "https://example.org/note", "any", {"lexicon": "empty"},
        )
    },
    weights={"https://example.org/stratum/lexical": retrieval.SCALE},
    statistics={"source": "host-statistics", "revision": "r1"},
    k=60, decay="reciprocal_rank", top_k=10,
)
assert len(ranking["rows"]) == 2
assert isinstance(ranking["rows"][0]["score"], str)

规则、深度与文档检查

权重是以原始定点单位表示的 Python 整数：SCALE 为一个完整单位，SCALE_DIGITS 为其指数。分数和贡献返回精确十进制字符串，绝不是浮点近似。k、decay 和 top_k 均显式指定。reciprocal_rank 先截断倒数再乘权重；weighted_reciprocal_rank 对加权商只舍入一次。两者是不同的内容寻址规则。将原始权重 1 与按 SCALE 倍数表示的权重混用，会使权重比例改变该倍数。

top_k 也是计划输入。在不相交候选域上，它可以在保留答案的同时减少读取。编译单元的 depth 是可报告的行界限；其 SPARQL LIMIT 比该界限多一行，用于探测。不要将探测行报告为值，也不要从查询文本读取界限。declared_rows=None 表示没有声明行数，不是零。调用 compile 时，weights、k 和 decay 必须同时提供或同时省略；没有规则时不会编造排名分辨率声明。

canonical_bytes 和 plan_id 标识计划。certify_plan 检查收到文档中记录的深度推导及所查询统计的投影，不认证外部统计是否最新。explain_depth 读取记录的限制原因，不执行认证。对被拒文档应按 retrieval.PlanDocumentError.refusal 分支。

设计期查询为 weight_for_depth、class_width、deepest_rank_within_width 和 crossing_rank_at，依次查询最小区分权重、某排名的等贡献类宽度、宽度容差内的最深前缀，以及超过融合阈值的首项排名。None 表示可表达排名域内没有有限结果，不是测得的极大数。输入必须满足规则对正权重、排名、平滑参数和容差的约束。宽度容差查询遍历非单调曲线并持有 GIL，应在设计时使用，不放在热点循环中。

读取排名证据

保留三个身份：plan_id 标识问题和计划输入，profile_id 标识融合规则，evidence_id 标识回答所用的索引代次与排除证据。planned_resolution 描述执行前深度；observed_resolution 报告已读取排名、碰撞、排除查找和物化行数。提前认证可使实际工作更少，但这不是对计划的修正。

应结合 fidelities 读取各分层的终止 statuses。exhausted 表示该搜索不再产生行，不表示有损搜索找到了所有可能匹配。depth_reached、row_bound_reached 和 ceiling_reached 是不同停止条件。共享词汇还包括用于更广泛 Rust 生成方与包接口的 supplied_query_ended、execution_failed 和 terms_rejected；不要将它们合并为空结果标志。

attestations 记录索引代次及准入的不完整性；fidelities 独立记录完整或有损搜索、忠实或扰动顺序，以及生成方自身的原因。未声明索引完整性不能证明覆盖整个语料。即使 HNSW 图由所提供向量精确构建，它仍是有损生成方。

exactness 指明缺失、膨胀和无界分层。候选缺失可能使其他候选排名上升，因此降级证据既可能使分数偏高，也可能使其偏低。每行的 interval 量化有界误差，或列出顺序受扰动的分层；certain_prefix 统计在所声明降级下仍保持位置的前导行。unemitted_ceiling 限制答案之外候选可能达到的分数；若顺序扰动使有限界限不可得，则为 None。这些声明涉及成员资格，并不证明每个未返回项都不存在。应将 domains 和 exclusion_bases 与授权跳过流的证据一起保留。参见检索设计。

错误与边界选择

无效配置、资源拒绝、表达式错误和经认证的部分结果是不同结果。若提供结构化诊断属性，应保留它们：message_id 和 presentation 标识原生失败；ShapesImportError.kind、ShapesProductError.dimension 和 PlanDocumentError.refusal 分别是对应的稳定区分字段。不要解析本地化消息文本来判断结果是否完整。未绑定 SELECT 单元格既不是缺失列，也不一定是异常。

迁移 rdflib 使用方时，请阅读 rdflib 兼容章节。query_rdflib 接受其命名图与默认图控制，原生入口保留这里所述的契约。单独的 purrdf-rdflib 替身发行包占用 rdflib 导入名，不能与真正的 rdflib 共享环境。公开调用直接通过 purrdf，不要使用内部 purrdf_native 扩展模块。