Package com.cockroachlabs.data.ai.annotation

Annotation Interface SemanticSearch

@Target(METHOD) @Retention(RUNTIME) @Documented public @interface SemanticSearch

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    table
    Table containing both vector and relational data.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    beamSize
    Beam size hint for vector search accuracy.
    String[]
    columns
    Columns to SELECT alongside the distance.
    String
    filter
    SQL WHERE clause for structured filtering (appended after vector search).
    int
    limit
    Maximum number of results to return.
    double
    maxDistance
    Maximum distance threshold — results farther than this are excluded.
    DistanceMetric
    metric
    Distance metric for similarity comparison.
    String[]
    prefixColumns
    Prefix columns for the vector index (CockroachDB v26.2+).
    String
    queryParam
    Name of the method parameter holding the query vector (float[]).
    boolean
    readOnly
    Run inside a read-only transaction for consistency.
    String
    vectorColumn
    Column name storing the vector embeddings.

  • Element Details

    • table

      String table
      Table containing both vector and relational data.

    • vectorColumn

      String vectorColumn
      Column name storing the vector embeddings.
      Default:
      "embedding"

    • metric

      DistanceMetric metric
      Distance metric for similarity comparison.
      Default:
      COSINE

    • limit

      int limit
      Maximum number of results to return.
      Default:
      10

    • queryParam

      String queryParam
      Name of the method parameter holding the query vector (float[]).
      Default:
      "queryVector"

    • filter

      String filter
      SQL WHERE clause for structured filtering (appended after vector search). Supports Spring Expression Language (SpEL) with method parameter references. Example: "category = :category AND active = true"
      Default:
      ""

    • columns

      String[] columns
      Columns to SELECT alongside the distance. Empty = all columns.
      Default:
      {}

    • readOnly

      boolean readOnly
      Run inside a read-only transaction for consistency.
      Default:
      true

    • beamSize

      int beamSize
      Beam size hint for vector search accuracy. 0 = database default.
      Default:
      0

    • maxDistance

      double maxDistance
      Maximum distance threshold — results farther than this are excluded. A value <= 0 disables the threshold.
      Default:
      0.0

    • prefixColumns

      String[] prefixColumns
      Prefix columns for the vector index (CockroachDB v26.2+).

      Prefix columns enable pre-filtering in the vector index itself, avoiding a full scan. They must appear before the vector column in the CREATE VECTOR INDEX statement.

      Example: prefixColumns = {"tenant_id"} generates: 

      CREATE VECTOR INDEX ON table (tenant_id, embedding vector_cosine_ops)
      Default:
      {}