> ## Documentation Index > Fetch the complete documentation index at: https://manual.seahorse.dnotitia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search API > Search API that supports dense, sparse, and hybrid search with text or vector queries. ## OpenAPI ````yaml POST /v2/data/search openapi: 3.1.0 info: title: Seahorse API Gateway description: >- Seahorse API Gateway is an API gateway that integrates vector database, AI inference, and storage services. It provides features such as vector search, embedding generation, text generation, and object storage. license: name: '' version: 2.0.0-rc1 servers: - url: https://{resource_uuid}.api.seahorse.dnotitia.ai description: >- 리소스(스토리지/테이블/인퍼런스 endpoint)별 UUID 서브도메인. UUID 는 콘솔 → 리소스 상세 페이지 "API URL" 항목에서 확인 variables: resource_uuid: default: your-resource-uuid-here description: '대시 제거된 32자리 UUID (예: b0348a15cf0e48079e290fe03901247b)' security: [] tags: - name: TABLE_V2 description: Table operations v2 - name: STORAGE description: Storage Object operations paths: /v2/data/search: post: tags: - TABLE_V2 summary: Search API description: >- Search API that supports dense, sparse, and hybrid search with text or vector queries. operationId: search_handler_v2 parameters: - name: include_metrics in: query description: Include metrics in the response. Default is false. required: false schema: type: boolean example: 'false' requestBody: description: >- Search request supporting dense/sparse modes with vector or text queries content: application/json: schema: $ref: '#/components/schemas/SearchRequest' examples: Dense Text Search: value: dense: column: dense_vector parameters: ef_search: 150 text: - Create a new trait within your crate. filter: id = '100' projection: id, text, metadata, distance search_mode: dense top_k: 10 Dense Vector Search: value: dense: column: dense_vector parameters: ef_search: 150 vector: - - 0.1 - 0.2 - 0.3 filter: id = '100' projection: id, text, metadata, distance search_mode: dense top_k: 10 Hybrid Search(RRF) (using text): value: dense: column: dense_vector parameters: ef_search: 150 text: - Create a new trait within your crate. filter: id = '100' fusion: parameters: alpha: 0.7 k: 60 type: rrf projection: id, text, metadata, score search_mode: hybrid sparse: column: sparse_vector parameters: b: 0.75 k: 1.2 text: - Create a new trait within your crate. top_k: 10 Hybrid Search(RRF) (using vector): value: dense: column: dense_vector parameters: ef_search: 150 vector: - - 0.1 - 0.2 - 0.3 filter: id = '100' fusion: parameters: alpha: 0.7 k: 60 type: rrf projection: id, text, metadata, score search_mode: hybrid sparse: column: sparse_vector metadata: 'N': 50001 avgdl: 200.51 df: 1:10000 5:8000 12:15000 23:7000 parameters: b: 0.75 k: 1.2 vector: - 1:0.8 5:0.6 12:0.4 23:0.7 top_k: 10 Sparse Text Search: value: filter: id = '100' projection: id, text, metadata, score search_mode: sparse sparse: column: sparse_vector parameters: b: 0.75 k: 1.2 text: - Create a new trait within your crate. top_k: 10 Sparse Vector Search: value: filter: id = '100' projection: id, text, metadata, score search_mode: sparse sparse: column: sparse_vector metadata: 'N': 50001 avgdl: 200.51 df: 1:10000 5:8000 12:15000 23:7000 parameters: b: 0.75 k: 1.2 vector: - 1:0.8 5:0.6 12:0.4 23:0.7 top_k: 10 required: true responses: '200': description: Successfully performed search content: application/json: schema: $ref: '#/components/schemas/CoralResponse_MultipleResultSetResponse' examples: Dense Vector Search Result: value: code: 200 data: data: - - distance: 0.10213412 id: '1' metadata: '{"file_name": "abc.pdf"}' text: hello - distance: 0.20213412 id: '2' metadata: '{"file_name": "def.pdf"}' text: world - distance: 0.30213412 id: '3' metadata: '{"file_name": "ghi.pdf"}' text: rust - - distance: 0.15223412 id: '4' metadata: '{"file_name": "jkl.pdf"}' text: python - distance: 0.25223412 id: '5' metadata: '{"file_name": "mno.pdf"}' text: java - distance: 0.35223412 id: '6' metadata: '{"file_name": "pqr.pdf"}' text: go metrics: null num_resultsets: 2 schema: fields: - data_type: LargeUtf8 name: id nullable: false - data_type: LargeUtf8 name: metadata nullable: false - data_type: LargeUtf8 name: text nullable: false - data_type: Float32 name: distance nullable: false metadata: {} exception: null success: true Hybrid Search(RRF) Result: value: code: 200 data: data: - - id: '1' metadata: '{"file_name": "abc.pdf"}' score: 0.95213412 text: hello - id: '2' metadata: '{"file_name": "def.pdf"}' score: 0.85213412 text: world - id: '3' metadata: '{"file_name": "ghi.pdf"}' score: 0.75213412 text: rust - - id: '4' metadata: '{"file_name": "jkl.pdf"}' score: 0.90223412 text: python - id: '5' metadata: '{"file_name": "mno.pdf"}' score: 0.80223412 text: java - id: '6' metadata: '{"file_name": "pqr.pdf"}' score: 0.70223412 text: go metrics: elapsed_time: 0.5 rss_peak_bytes: 52428800 num_resultsets: 2 schema: fields: - data_type: LargeUtf8 name: id nullable: false - data_type: LargeUtf8 name: metadata nullable: false - data_type: LargeUtf8 name: text nullable: false - data_type: Float32 name: score nullable: false metadata: {} exception: null success: true Sparse Vector Search Result: value: code: 200 data: data: - - id: '1' metadata: '{"file_name": "abc.pdf"}' score: 0.95213412 text: hello - id: '2' metadata: '{"file_name": "def.pdf"}' score: 0.85213412 text: world - id: '3' metadata: '{"file_name": "ghi.pdf"}' score: 0.75213412 text: rust - - id: '4' metadata: '{"file_name": "jkl.pdf"}' score: 0.90223412 text: python - id: '5' metadata: '{"file_name": "mno.pdf"}' score: 0.80223412 text: java - id: '6' metadata: '{"file_name": "pqr.pdf"}' score: 0.70223412 text: go metrics: elapsed_time: 0.5 rss_peak_bytes: 52428800 num_resultsets: 2 schema: fields: - data_type: LargeUtf8 name: id nullable: false - data_type: LargeUtf8 name: metadata nullable: false - data_type: LargeUtf8 name: text nullable: false - data_type: Float32 name: score nullable: false metadata: {} exception: null success: true '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/CoralResponse_ErrorBody' example: code: 400 data: null exception: error_code: 400001 error_message: 'Bad Request: ' success: false '500': description: Error occurred while searching content: application/json: schema: $ref: '#/components/schemas/CoralResponse_ErrorBody' example: code: 500 data: null exception: error_code: 500001 error_message: 'Internal error: ' success: false security: - bearerAuth: - READ - WRITE - apiKeyAuth: - READ - WRITE components: schemas: SearchRequest: type: object required: - top_k - search_mode properties: dense: oneOf: - type: 'null' - $ref: '#/components/schemas/DenseSearchConfig' description: Dense vector search configuration filter: type: - string - 'null' description: >- SQL WHERE clause to filter the results. If not specified, no filtering will be applied. default: '' example: id < 1000 fusion: oneOf: - type: 'null' - $ref: '#/components/schemas/FusionConfig' description: Fusion configuration for combining results projection: type: - string - 'null' description: >- Columns to include in the result set. Uses SQL projection syntax (e.g. "col1, col2"). If not specified, all columns will be returned. default: '*' example: id, name search_mode: $ref: '#/components/schemas/SearchMode' description: Search mode to use sparse: oneOf: - type: 'null' - $ref: '#/components/schemas/SparseSearchConfig' description: Sparse vector search configuration top_k: type: integer format: int32 description: >- Number of top results to return from the hybrid search. Must be greater than 0. example: '100' CoralResponse_MultipleResultSetResponse: type: object required: - success - code properties: code: type: integer format: int32 description: HTTP status code. minimum: 0 data: type: object required: - schema - num_resultsets - data properties: data: type: array items: {} description: >- Data of the single resultset in JSON format. Each row is represented as a JSON object in an JSON array. metrics: oneOf: - type: 'null' - $ref: '#/components/schemas/RequestMetrics' description: Metrics of the request. num_resultsets: type: integer format: int32 description: Number of resultsets minimum: 0 schema: description: Schema of the resultset. exception: type: object required: - schema - num_resultsets - data properties: data: type: array items: {} description: >- Data of the single resultset in JSON format. Each row is represented as a JSON object in an JSON array. metrics: oneOf: - type: 'null' - $ref: '#/components/schemas/RequestMetrics' description: Metrics of the request. num_resultsets: type: integer format: int32 description: Number of resultsets minimum: 0 schema: description: Schema of the resultset. success: type: boolean description: Whether the request was successful. CoralResponse_ErrorBody: type: object required: - success - code properties: code: type: integer format: int32 description: HTTP status code. minimum: 0 data: type: object required: - error_code - error_message properties: error_code: type: integer format: int32 minimum: 0 error_message: type: string exception: type: object required: - error_code - error_message properties: error_code: type: integer format: int32 minimum: 0 error_message: type: string success: type: boolean description: Whether the request was successful. DenseSearchConfig: allOf: - oneOf: - type: 'null' - $ref: '#/components/schemas/QueryText' description: Text query - type: object required: - column properties: column: type: string description: Column name containing dense vectors example: dense_vector parameters: oneOf: - type: 'null' - $ref: '#/components/schemas/DenseSearchParameters' description: Search parameters for dense vector search vector: type: - array - 'null' items: type: array items: type: number format: float description: >- Vector query: Dense vectors represented as fixed-size lists of floats example: '[[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]' FusionConfig: type: object required: - type properties: parameters: oneOf: - type: 'null' - $ref: '#/components/schemas/FusionParameters' description: Fusion parameters type: type: string description: Type of fusion algorithm to use example: rrf SearchMode: type: string enum: - dense - sparse - hybrid SparseSearchConfig: allOf: - oneOf: - type: 'null' - $ref: '#/components/schemas/QueryText' description: Text query - type: object required: - column properties: column: type: string description: Column name containing sparse vectors example: sparse_vector metadata: oneOf: - type: 'null' - $ref: '#/components/schemas/SparseMetadata' description: Metadata used by sparse model (BM25) parameters: oneOf: - type: 'null' - $ref: '#/components/schemas/SparseSearchParameters' description: 'Parameters for sparse model (BM25): k and b' vector: type: - array - 'null' items: type: string description: 'Vector query: Sparse vectors in format "index:value index:value"' example: '["1:0.5 2:0.3", "1:0.2 3:0.4"]' RequestMetrics: type: object required: - elapsed_time - rss_peak_bytes properties: elapsed_time: type: number format: float description: Elapsed time in seconds for the request. rss_peak_bytes: type: integer format: int64 description: Peak memory usage in bytes. minimum: 0 QueryText: type: object required: - text properties: text: type: array items: type: string description: Text query example: Create a new trait within your crate. DenseSearchParameters: type: object properties: ef_search: type: - integer - 'null' format: int32 description: >- Size of the dynamic candidate list during search. A larger value will result in more accurate but slower searches. example: '128' minimum: 0 FusionParameters: type: object properties: alpha: type: - number - 'null' format: float description: >- Weight parameter alpha for dense search (0.0 to 1.0). Sparse weight is automatically (1 - alpha). Default is 0.5 example: '0.5' k: type: - integer - 'null' format: int32 description: RRF parameter k value example: '60' minimum: 0 SparseMetadata: type: object required: - 'N' - avgdl - df properties: 'N': type: integer format: int64 description: Total number of documents (N) example: '50001' minimum: 0 avgdl: type: number format: float description: Average document length (avgdl) example: '200.51' df: $ref: '#/components/schemas/DocumentFrequencies' description: Term document frequencies SparseSearchParameters: type: object properties: b: type: - number - 'null' format: float description: |- BM25 b parameter: controls document length normalization (0..1) 0 = no length normalization, 1 = full length normalization Typical value: 0.75 (balanced approach) example: '0.75' k: type: - number - 'null' format: float description: |- BM25 k1 parameter: controls term frequency saturation Higher values (>1.2) give more weight to term frequency Lower values (<1.2) reduce the impact of term frequency Typical range: 1.2-2.0, Default: 1.2 example: '1.2' DocumentFrequencies: oneOf: - type: string description: |- Single query: "term_id:df term_id:df ..." Used in hybrid search (single query only) example: 205:30001 101:15000 102:8000 - type: array items: type: string description: |- Multiple queries: ["query1_df", "query2_df", ...] Used in vector search (multiple queries possible) example: '["205:30001 101:15000", "205:25000 101:12000"]' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Bearer token authentication. Include the token in the Authorization header as 'Bearer ' apiKeyAuth: type: apiKey in: header name: api-key description: API key authentication. Include the key in the api-key header ````