<span id="图纸检索返回对象"></span>

# Drawing search response objects

The following expands server JSON objects rather than the current narrower Go SDK types. Optional omission is distinguished from null and empty arrays.

## DrawingSearchResponse

| Field | Type | Description |
| --- | --- | --- |
| `drawings` | object[] | Results aggregated by source; [] when empty. |
| `count` | integer | Number returned, not a pagination total. |
| `match_mode` | string | exact/semantic. May be omitted for some early empty results. May be omitted when empty. |
| `diagnostics` | object | |

## DrawingSearchResult

| Field | Type | Description |
| --- | --- | --- |
| `source_file_id` | string | Source file identifier for aggregation and provenance. |
| `drawing_number` | string | Business drawing number, separate from drawing_id in exact results. May be omitted when empty. |
| `drawing_id` | string | CAD/drawing identifier, possibly falling back to source ID. Do not substitute it for source_file_id. |
| `score` | number | Ranking score for this request; not guaranteed equivalent across modes/channels or interpretable as probability. |
| `best_hit` | object | Best hit, using the hit object below. |
| `supporting_hits` | object[] or null | Supporting hits, at most 3 in semantic mode. Exact results may be null; semantic results without supporting hits use []. |
| `external_source_uri` | string or null | Source URI. Omitted when source information is not loaded; null when loaded without a URI. |
| `visual_manifest_file_id` | string or null | Manifest ID. Omitted when source information is not loaded; null when loaded without a manifest. |
| `provenance_status` | string | ready or legacy_unmigrated when the source is loaded. May be omitted when empty. |
| `gaps` | string[] or null | Gaps, as described in source objects. Omitted when not loaded; the current implementation may return null when loaded without gaps. |
| `pages` | object[] or null | Complete page list. Omitted when not loaded; the current implementation may return null when loaded without pages. |
| `default_version` | boolean | Only true marks the current version in keep_versions results; false is omitted. Omission does not mean the knowledge base has no current version. |

## DrawingSearchHit

| Field | Type | Description |
| --- | --- | --- |
| `object_id` | string | Retrieved object ID. May be omitted when empty. |
| `object_kind` | string | Object category. May be omitted when empty. |
| `retrieval_level` | string | Retrieval level, such as whole page/region; follow the returned value. May be omitted when empty. |
| `retrieval_channel` | string | Retrieval channel identifier. May be omitted when empty. |
| `retrieval_scope` | string | Retrieval scope marker. May be omitted when empty. |
| `source_file_id` | string | Source file identifier for aggregation and provenance. |
| `drawing_id` | string | CAD/drawing identifier, possibly falling back to source ID. Do not substitute it for source_file_id. May be omitted when empty. |
| `image_file_id` | string | Local or object image ID. May be omitted when empty. |
| `page_image_file_id` | string | Registered page image file ID. May be omitted when empty. |
| `page_number` | integer | Associated positive page number. May be omitted when empty. |
| `bbox` | number[] | Bounding box coordinates, interpreted with coordinate_space; not necessarily normalized. May be omitted when empty. |
| `score` | number | Ranking score for this request; not guaranteed equivalent across modes/channels or interpretable as probability. |
| `content` | string | Hit content. May be omitted when empty. |
| `modality` | string | Hit modality. May be omitted when empty. |
| `reason` | string | Hit reason marker. May be omitted when empty. |
| `channel` | string | Hit channel. May be omitted when empty. |
| `text_id` | string | Text evidence ID. May be omitted when empty. |
| `text_kind` | string | Text kind, such as dimension/technical_requirement. May be omitted when empty. |
| `canonical_text` | string | Normalized evidence text. May be omitted when empty. |
| `recognition_status` | string | Recognition state, determined by returned values; absence does not imply recognized. May be omitted when empty. |
| `status_reasons` | string[] | Recognition-state reason marker. May be omitted when empty. |
| `coordinate_space` | string | Coordinate space, such as source_page_px. May be omitted when empty. |
| `source_refs` | object[] | Pointer object for tracing OCR/VLM sources. May be omitted when empty. |
| `structured_refs` | string[] | Associated structured record identifier. May be omitted when empty. |
| `dimension_candidate` | object | Extracted dimension observation candidates, not approved engineering facts. May be omitted when empty. |

## DrawingSearchSourceRef

| Field | Type | Description |
| --- | --- | --- |
| `artifact` | string | Source artifact identifier. May be omitted when empty. |
| `json_pointer` | string | JSON Pointer within the artifact. May be omitted when empty. |
| `method` | string | Extraction method, such as crop_ocr. May be omitted when empty. |

## DrawingSearchDimensionCandidate

| Field | Type | Description |
| --- | --- | --- |
| `text_id` | string | Text evidence ID. May be omitted when empty. |
| `region_id` | string | Associated region ID. May be omitted when empty. |
| `attr_label` | string | Property name. May be omitted when empty. |
| `geometry_role` | string | Geometry role marker. May be omitted when empty. |
| `nominal` | number | Candidate nominal value. Omitted when unset; 0 is also valid. |
| `tol_text` | string | Original tolerance text. May be omitted when empty. |
| `value_min` | number | Candidate lower bound. Omitted when unset; 0 is also valid. |
| `value_max` | number | Candidate upper bound. Omitted when unset; 0 is also valid. |
| `unit` | string | Candidate unit. May be omitted when empty. |
| `raw_text` | string | Original dimension text. May be omitted when empty. |
| `authority` | string | Extraction authority/candidate marker; still verify against the source. May be omitted when empty. |

## DrawingSearchPage

| Field | Type | Description |
| --- | --- | --- |
| `page_number` | integer | Associated positive page number. |
| `page_image_file_id` | string | Registered page image file ID. |
| `preview_url` | string | Authenticated relative API path in the same environment. |

## DrawingSearchDiagnostics

| Field | Type | Description |
| --- | --- | --- |
| `total_ms` | integer | |
| `plan_ms` | integer | |
| `embed_ms` | integer | May be omitted when empty. |
| `text_retrieve_ms` | integer | May be omitted when empty. |
| `image_retrieve_ms` | integer | May be omitted when empty. |
| `merge_ms` | integer | |
| `aggregate_ms` | integer | |
| `channels` | string[] | |
| `candidate_hit_count` | integer | Number of merged candidate hits. |
| `unique_drawing_count` | integer | Distinct source drawings among candidates, not the entire knowledge base count. |
| `result_count` | integer | Number of results in this response. |
| `identifier_route_used` | boolean | Whether identifier-related retrieval was attempted; not equivalent to exact mode. |
| `extracted_identifiers` | string[] | Identifier hint extracted from query. May be omitted when empty. |
| `identifier_hit_count` | integer | Identifier-related hit count. |
| `identifier_filename_hit_count` | integer | Filename identifier hit count. |
| `identifier_l1_hit_count` | integer | Text-layer identifier hit count. |
| `vector_hit_count` | integer | Vector-related hit count. |

Search-attached source objects copy gaps/pages; empty slices may encode as null, unlike [] returned by separate provenance objects. CLI may omit them further. Do not conflate null, [], and absence.
