1---
2id: post-search
3title: "Search"
4description: "Perform a vector similarity search (VSS) operation on a dataset."
5sidebar_label: "Search"
6hide_title: true
7hide_table_of_contents: true
8api: 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
9sidebar_class_name: "post api-method"
10info_path: docs/api/HTTP/runtime
11custom_edit_url: null
12proxy: http://localhost:8090
13---
14
15import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
16import ParamsDetails from "@theme/ParamsDetails";
17import RequestSchema from "@theme/RequestSchema";
18import StatusCodes from "@theme/StatusCodes";
19import OperationTabs from "@theme/OperationTabs";
20import TabItem from "@theme/TabItem";
21import Heading from "@theme/Heading";
22
23<Heading
24 as={"h1"}
25 className={"openapi__heading"}
26 children={"Search"}
27>
28</Heading>
29
30<MethodEndpoint
31 method={"post"}
32 path={"/v1/search"}
33 context={"endpoint"}
34>
35
36</MethodEndpoint>
37
38
39
40Perform a vector similarity search (VSS) operation on a dataset.
41
42The search operation will return the most relevant matches based on cosine similarity with the input `text`.
43The datasets queries should have an embedding column, and the appropriate embedding model loaded.
44
45<Heading
46 id={"request"}
47 as={"h2"}
48 className={"openapi-tabs__heading"}
49 children={"Request"}
50>
51</Heading>
52
53<ParamsDetails
54 parameters={undefined}
55>
56
57</ParamsDetails>
58
59<RequestSchema
60 title={"Body"}
61 body={{"description":"Search request parameters","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["text"],"properties":{"additional_columns":{"type":"array","items":{"type":"string"},"description":"Additional columns to return from the dataset."},"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"The datasets to search for similarity. If None, search across all datasets. For available datasets, use the `list_datasets` tool and ensure `can_search_documents==true`."},"limit":{"type":["integer","null"],"description":"Number of documents to return for each dataset","minimum":0},"text":{"type":"string","description":"The text to search documents for similarity"},"where":{"type":["string","null"],"description":"An SQL filter predicate to apply. Format: 'WHERE `where_cond`'."}},"title":"SearchRequestBaseJson"},{"type":"object","properties":{"keywords":{"type":["array","null"],"items":{"type":"string"}}}}],"description":"HTTP request schema is separate from AI requests, so that keywords can be supplied as an optional field for HTTP calls.\n`schemars` doesn't allow setting `#[serde(default)]` as well as `#[schemars(required)]` - the field does not become required.\nWhen the field is not required, the model ignores it.","title":"SearchRequestHTTPJson"},"example":{"datasets":["app_messages"],"text":"Tokyo plane tickets","where":"user=1234321","additional_columns":["timestamp"],"limit":3,"keywords":["plane","tickets"]}}},"required":true}}
62>
63
64</RequestSchema>
65
66<StatusCodes
67 id={undefined}
68 label={undefined}
69 responses={{"200":{"description":"Search completed successfully","content":{"application/json":{"schema":{"type":"object","required":["matches","duration_ms"],"properties":{"duration_ms":{"type":"integer","description":"Total time taken to execute the search, in milliseconds","minimum":0},"matches":{"type":"array","items":{"type":"object","required":["value","score","dataset"],"properties":{"dataset":{"type":"string","description":"The name of the dataset where the match was found"},"metadata":{"type":"object","description":"Additional metadata for the match, requested explicitly by the user.","additionalProperties":{},"propertyNames":{"type":"string"}},"primary_key":{"type":"object","description":"Primary key(s) identifying the matched item in the dataset","additionalProperties":{},"propertyNames":{"type":"string"}},"score":{"type":"number","format":"double","description":"The similarity of the match to the query"},"value":{"type":"string","description":"The value of the match (e.g., document snippet, identifier, etc.)"}},"title":"Match"},"description":"List of matches that were found in the datasets"}},"title":"SearchResponse"},"example":{"matches":[{"value":"I booked use some tickets","dataset":"app_messages","primary_key":{"id":"6fd5a215-0881-421d-ace0-b293b83452b5"},"metadata":{"timestamp":1724716542}},{"value":"direct to Narata","dataset":"app_messages","primary_key":{"id":"8a25595f-99fb-4404-8c82-e1046d8f4c4b"},"metadata":{"timestamp":1724715881}},{"value":"Yes, we're sitting together","dataset":"app_messages","primary_key":{"id":"8421ed84-b86d-4b10-b4da-7a432e8912c0"},"metadata":{"timestamp":1724716123}}],"duration_ms":42}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{},"example":{"error":"No data sources provided"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{},"example":{"error":"Unexpected internal server error occurred"}}}}}}
70>
71
72</StatusCodes>
73
74
75
1---
2id: post-search
3title: "Search"
4description: "Perform a vector similarity search (VSS) operation on a dataset."
5sidebar_label: "Search"
6hide_title: true
7hide_table_of_contents: true
8api: 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
9sidebar_class_name: "post api-method"
10info_path: docs/api/HTTP/runtime
11custom_edit_url: null
12proxy: http://localhost:8090
13---
14
15import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
16import ParamsDetails from "@theme/ParamsDetails";
17import RequestSchema from "@theme/RequestSchema";
18import StatusCodes from "@theme/StatusCodes";
19import OperationTabs from "@theme/OperationTabs";
20import TabItem from "@theme/TabItem";
21import Heading from "@theme/Heading";
22
23<Heading
24 as={"h1"}
25 className={"openapi__heading"}
26 children={"Search"}
27>
28</Heading>
29
30<MethodEndpoint
31 method={"post"}
32 path={"/v1/search"}
33 context={"endpoint"}
34>
35
36</MethodEndpoint>
37
38
39
40Perform a vector similarity search (VSS) operation on a dataset.
41
42The search operation will return the most relevant matches based on cosine similarity with the input `text`.
43The datasets queries should have an embedding column, and the appropriate embedding model loaded.
44
45<Heading
46 id={"request"}
47 as={"h2"}
48 className={"openapi-tabs__heading"}
49 children={"Request"}
50>
51</Heading>
52
53<ParamsDetails
54 parameters={undefined}
55>
56
57</ParamsDetails>
58
59<RequestSchema
60 title={"Body"}
61 body={{"description":"Search request parameters","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["text"],"properties":{"additional_columns":{"type":"array","items":{"type":"string"},"description":"Additional columns to return from the dataset."},"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"The datasets to search for similarity. If None, search across all datasets. For available datasets, use the `list_datasets` tool and ensure `can_search_documents==true`."},"limit":{"type":["integer","null"],"description":"Number of documents to return for each dataset","minimum":0},"text":{"type":"string","description":"The text to search documents for similarity"},"where":{"type":["string","null"],"description":"An SQL filter predicate to apply. Format: 'WHERE `where_cond`'."}},"title":"SearchRequestBaseJson"},{"type":"object","properties":{"keywords":{"type":["array","null"],"items":{"type":"string"}}}}],"description":"HTTP request schema is separate from AI requests, so that keywords can be supplied as an optional field for HTTP calls.\n`schemars` doesn't allow setting `#[serde(default)]` as well as `#[schemars(required)]` - the field does not become required.\nWhen the field is not required, the model ignores it.","title":"SearchRequestHTTPJson"},"example":{"datasets":["app_messages"],"text":"Tokyo plane tickets","where":"user=1234321","additional_columns":["timestamp"],"limit":3,"keywords":["plane","tickets"]}}},"required":true}}
62>
63
64</RequestSchema>
65
66<StatusCodes
67 id={undefined}
68 label={undefined}
69 responses={{"200":{"description":"Search completed successfully","content":{"application/json":{"schema":{"type":"object","required":["matches","duration_ms"],"properties":{"duration_ms":{"type":"integer","description":"Total time taken to execute the search, in milliseconds","minimum":0},"matches":{"type":"array","items":{"type":"object","required":["value","score","dataset"],"properties":{"dataset":{"type":"string","description":"The name of the dataset where the match was found"},"metadata":{"type":"object","description":"Additional metadata for the match, requested explicitly by the user.","additionalProperties":{},"propertyNames":{"type":"string"}},"primary_key":{"type":"object","description":"Primary key(s) identifying the matched item in the dataset","additionalProperties":{},"propertyNames":{"type":"string"}},"score":{"type":"number","format":"double","description":"The similarity of the match to the query"},"value":{"type":"string","description":"The value of the match (e.g., document snippet, identifier, etc.)"}},"title":"Match"},"description":"List of matches that were found in the datasets"}},"title":"SearchResponse"},"example":{"matches":[{"value":"I booked use some tickets","dataset":"app_messages","primary_key":{"id":"6fd5a215-0881-421d-ace0-b293b83452b5"},"metadata":{"timestamp":1724716542}},{"value":"direct to Narata","dataset":"app_messages","primary_key":{"id":"8a25595f-99fb-4404-8c82-e1046d8f4c4b"},"metadata":{"timestamp":1724715881}},{"value":"Yes, we're sitting together","dataset":"app_messages","primary_key":{"id":"8421ed84-b86d-4b10-b4da-7a432e8912c0"},"metadata":{"timestamp":1724716123}}],"duration_ms":42}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{},"example":{"error":"No data sources provided"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{},"example":{"error":"Unexpected internal server error occurred"}}}}}}
70>
71
72</StatusCodes>
73
74
75