데이터 객체 검색

Search API의 목적은 지정된 쿼리와 유사한 데이터 객체를 찾아 유사성별로 순위가 지정된 결과 목록을 반환하는 것입니다. 검색 API는 필터링도 지원합니다.

Search API는 벡터 검색, 전체 텍스트 검색, 시맨틱 검색 등 다양한 방법으로 데이터 객체를 검색할 수 있습니다. 또한 모든 유형의 여러 검색을 결합하여 하이브리드 검색을 구현할 수 있습니다.

벡터 검색을 사용하면 자체 쿼리 벡터를 제공할 수 있습니다. embedding-config가 없는 임베딩 필드를 검색하는 데 필요한 메서드입니다. vector_search 필드가 여러 개 제공되면 동일한 가중치를 사용하여 결과가 결합됩니다.

다음 예시에서는 ID가 COLLECTION_ID인 컬렉션에서 벡터 검색을 실행하는 방법을 보여줍니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID

HTTP 메서드 및 URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search

JSON 요청 본문:

{
  "vector_search": {
    "search_field": "plot_embedding",
    "vector": {
      "values": [
        0.42426406871192845,
        0.565685424949238,
        0.7071067811865475
      ]
    },
    "filter": {
      "genre": {
        "$eq": "Thriller"
      }
    },
    "top_k": 5,
    "output_fields": {
      "data_fields": "*",
      "vector_fields": "*",
      "metadata_fields": "*"
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "results": [
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
        "createTime": "2026-01-31T20:05:06Z",
        "updateTime": "2026-02-02T13:59:24Z",
        "data": {
          "year": 1991,
          "title": "The Silence of the Lambs",
          "director": "Jonathan Demme",
          "genre": "Thriller"
        },
        "vectors": {
          "plot_embedding": {
            "dense": {
              "values": [
                1,
                1,
                1
              ]
            }
          },
          "sparse_embedding": {
            "sparse": {
              "values": [
                1,
                6,
                3,
                2,
                8,
                5,
                2
              ],
              "indices": [
                4065,
                13326,
                17377,
                25918,
                28105,
                32683,
                42998
              ]
            }
          },
          "genre_embedding": {
            "dense": {
              "values": [
                0.3863801,
                0.73934346,
                0.16189057,
                0.5271367
              ]
            }
          },
          "soundtrack_embedding": {
            "dense": {
              "values": [
                0.5920452,
                0.08301644,
                0.12647335,
                0.619643,
                0.49258286
              ]
            }
          }
        }
      },
      "distance": 1.697
    },
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
        "createTime": "2026-02-04T14:35:29Z",
        "updateTime": "2026-02-04T14:37:29Z",
        "data": {
          "year": 1995,
          "title": "Se7en",
          "director": "David Fincher",
          "genre": "Thriller"
        },
        "vectors": {
          "genre_embedding": {
            "dense": {
              "values": [
                0.3863801,
                0.73934346,
                0.16189057,
                0.5271367
              ]
            }
          },
          "plot_embedding": {
            "dense": {
              "values": [
                1,
                1,
                1
              ]
            }
          },
          "sparse_embedding": {
            "sparse": {
              "values": [
                1,
                6,
                3,
                2,
                8,
                5,
                2
              ],
              "indices": [
                4065,
                13326,
                17377,
                25918,
                28105,
                32683,
                42998
              ]
            }
          },
          "soundtrack_embedding": {
            "dense": {
              "values": [
                0.5920452,
                0.08301644,
                0.12647335,
                0.619643,
                0.49258286
              ]
            }
          }
        }
      },
      "distance": 1.75
    }
  ]
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • SEARCH_VECTOR_FILE: 검색할 밀도 벡터 또는 희소 벡터가 포함된 JSON 파일의 로컬 경로입니다.

    밀도 높은 벡터의 파일 콘텐츠 예:

    {
  "dense": {
    "values": [
      0.42426406871192845,
      0.565685424949238,
      0.7071067811865475
    ]
  }
}

    희소 벡터의 파일 콘텐츠 예:

    {
  "sparse": {
    "indices": [1, 5, 10],
    "values": [0.1, 0.5, 0.21]
  }
}
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects search \
  --vector-search-field="plot_embedding" \
  --vector-from-file=SEARCH_VECTOR_FILE \
  --json-filter='{"genre": {"$eq": "Thriller"}}' \
  --top-k=5 \
  --output-data-fields='*' \
  --output-vector-fields='*' \
  --output-metadata-fields='*' \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows(PowerShell)

gcloud vector-search collections data-objects search `
  --vector-search-field="plot_embedding" `
  --vector-from-file=SEARCH_VECTOR_FILE `
  --json-filter='{"genre": {"$eq": "Thriller"}}' `
  --top-k=5 `
  --output-data-fields='*' `
  --output-vector-fields='*' `
  --output-metadata-fields='*' `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows(cmd.exe)

gcloud vector-search collections data-objects search ^
  --vector-search-field="plot_embedding" ^
  --vector-from-file=SEARCH_VECTOR_FILE ^
  --json-filter='{"genre": {"$eq": "Thriller"}}' ^
  --top-k=5 ^
  --output-data-fields='*' ^
  --output-vector-fields='*' ^
  --output-metadata-fields='*' ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

다음과 비슷한 응답이 표시됩니다.

---
dataObject:
  createTime: '2026-01-31T20:05:06Z'
  data:
    director: Jonathan Demme
    genre: Thriller
    title: The Silence of the Lambs
    year: 1991
  name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
  updateTime: '2026-02-02T13:59:24Z'
  vectors:
    genre_embedding:
      dense:
        values:
        - 0.38638
        - 0.739343
        - 0.161891
        - 0.527137
    plot_embedding:
      dense:
        values:
        - 1.0
        - 1.0
        - 1.0
    soundtrack_embedding:
      dense:
        values:
        - 0.592045
        - 0.0830164
        - 0.126473
        - 0.619643
        - 0.492583
    sparse_embedding:
      sparse:
        indices:
        - 4065
        - 13326
        - 17377
        - 25918
        - 28105
        - 32683
        - 42998
        values:
        - 1.0
        - 6.0
        - 3.0
        - 2.0
        - 8.0
        - 5.0
        - 2.0
distance: 1.697
---
dataObject:
  createTime: '2026-02-04T14:35:29Z'
  data:
    director: David Fincher
    genre: Thriller
    title: Se7en
    year: 1995
  name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
  updateTime: '2026-02-04T14:37:29Z'
  vectors:
    genre_embedding:
      dense:
        values:
        - 0.38638
        - 0.739343
        - 0.161891
        - 0.527137
    plot_embedding:
      dense:
        values:
        - 1.0
        - 1.0
        - 1.0
    soundtrack_embedding:
      dense:
        values:
        - 0.592045
        - 0.0830164
        - 0.126473
        - 0.619643
        - 0.492583
    sparse_embedding:
      sparse:
        indices:
        - 4065
        - 13326
        - 17377
        - 25918
        - 28105
        - 32683
        - 42998
        values:
        - 1.0
        - 6.0
        - 3.0
        - 2.0
        - 8.0
        - 5.0
        - 2.0
distance: 1.75

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
    search_field="plot_embedding",
    vector={"values": [0.1, 0.2, 0.3]},
    filter={"genre": {"$eq": "Thriller"}},
    top_k=5,
)
request = vectorsearch_v1.SearchDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    vector_search=vector_search,
)

# Make the request
response = data_object_search_service_client.search_data_objects(request=request)

# Handle the response
print(response)

검색 정확도 및 성능 조정

100,000개가 넘는 임베딩이 있는 밀도 높은 ANN 색인에 대한 벡터 검색의 경우 에이전트 검색은 기본적으로 재현율과 지연 시간 간의 최적의 절충안을 제공하려고 시도합니다. 타겟 재현율을 지정하여 사용 사례에 맞게 이 균형을 조정할 수 있습니다.

값은 0.00 이상, 1.00 이하여야 합니다.

ANN 색인을 만드는 방법에 대한 자세한 내용은 ANN 색인 만들기를 참고하세요.

다음 예시에서는 타겟 재현율이 0.95인 밀도 높은 ANN 색인에서 벡터 검색을 실행하는 방법을 보여줍니다.

REST

HTTP 메서드 및 URL:

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search

JSON 요청 본문:

{
  "vectorSearch": {
    "searchField": "plot_embedding",
    "vector": {
      "values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
    },
    "topK": 10,
    "searchHint": {
      "indexHint": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
        "denseScannParams": {
          "targetRecall": 0.95
        }
      }
    },
    "outputFields": {
      "dataFields": "*",
      "vectorFields": "*",
      "metadataFields": "*"
    }
  }
}

gcloud

쿼리 벡터를 JSON 파일(예: vector.json)에 저장합니다.

{
  "dense": {
    "values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
  }
}

그런 다음 gcloud vector-search collections data-objects search 명령어를 실행합니다.

gcloud vector-search collections data-objects search \
    --project=PROJECT_ID \
    --location=LOCATION \
    --collection=COLLECTION_ID \
    --vector-search-field=plot_embedding \
    --vector-from-file=vector.json \
    --use-index=INDEX_ID \
    --dense-scann-target-recall=0.95 \
    --top-k=10

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

collection = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Set the target recall rate on the index hint
search_hint = vectorsearch_v1.SearchHint(
    index_hint=vectorsearch_v1.SearchHint.IndexHint(
        name=f"{collection}/indexes/INDEX_ID",
        dense_scann_params=vectorsearch_v1.SearchHint.IndexHint.DenseScannParams(
            target_recall=0.95,
        ),
    ),
)

# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
    search_field="plot_embedding",
    vector={"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]},
    top_k=10,
    search_hint=search_hint,
    output_fields=vectorsearch_v1.OutputFields(
        data_fields=["*"],
        vector_fields=["*"],
        metadata_fields=["*"],
    ),
)
request = vectorsearch_v1.SearchDataObjectsRequest(
    parent=collection,
    vector_search=vector_search,
)

# Make the request
response = data_object_search_service_client.search_data_objects(request=request)

# Handle the response
print(response)

텍스트 검색

이렇게 하면 희소 벡터 없이 전체 텍스트 검색이 실행됩니다. 기본 '단어' 쿼리 언어는 전체 입력을 암시적 AND 연산자가 있는 개별 검색어로 취급합니다. enhanced_query를 true로 설정하여 검색어를 확장하고, 어간 추출, 불용어 삭제를 처리하고, 추가 검색 연산자를 허용할 수 있습니다.

  • OR: 지정된 검색어 중 하나 이상이 포함된 문서와 일치하는 대소문자를 구분하는 논리합 연산자입니다. 이는 인접한 두 검색어에만 적용됩니다.

  • ": 구문 검색을 위한 큰따옴표입니다.

  • -: 부정 연산자입니다. 이 용어 앞에 배치된 용어가 포함된 문서는 제외됩니다.

고급 텍스트 검색

Agent Retrieval 텍스트 검색 API를 사용하면 하나 이상의 하위 쿼리가 포함된 구조화된 쿼리를 통해 텍스트 검색을 표현할 수 있습니다. 이를 통해 다음 작업을 할 수 있습니다.

  • 특정 데이터 객체 필드와 일치시킵니다.

  • 실행할 일치의 유형을 지정합니다.

    • 검색어별, 대소문자 구분 안 함

    • 정확히, 대소문자 구분

  • 용어 어간, 동의어, 맞춤법 오류, 불용어('a', 'an', 'the' 등)와 일치하도록 언어별 개선사항을 포함합니다.

  • AND, OR, NOT 불리언 연산자를 사용하여 하위 쿼리를 결합합니다.

  • 하위 쿼리를 함께 그룹화하여 평가 순서를 제어합니다.

  • 부스트 점수 기여도를 높여 순위에 영향을 미칩니다.

서브 쿼리에는 세 가지 유형이 있습니다.

  • 텍스트: 검색 텍스트와 일치시킬 하나 이상의 필드를 제공합니다.

  • 단항: 단일 하위 쿼리에 NOT 작업을 적용합니다.

  • 결합: AND 또는 OR 연산자를 적용하여 하위 쿼리를 결합하며, 다른 결합된 하위 쿼리를 그룹화하여 평가 순서를 제어하는 데 사용할 수 있습니다.

이 페이지의 예시에서는 다음 표에 표시된 Collection을 사용합니다. 여기에는 6개의 데이터 객체가 포함되어 있으며 데이터 스키마에 문자열 ID, Title, Description, 문자열 배열 Keywords과 같은 필드가 정의되어 있습니다.

ID 제목 설명 키워드
1 The Quick Brown Fox 빠른 갈색 여우가 게으른 개를 쉽게 뛰어넘습니다. 야생, 숲, 포유류, 주황색, 민첩성, 포식자
2 Lazy Dog Days 갈색 개가 잠을 자고 있습니다. 국내, 반려동물, 집, 개, 차분함, 게으름, 순종
3 여우 대 개 빠른 여우가 개를 속입니다. 야생, 가축, 갈등, 개아목, 포유류, 상호작용
4 브라운 베어스 숲 속에서 빠르게 움직입니다. 야생, 숲, 곰, 최상위 포식자, 동면, 거대
5 여우 이야기 개가 높이 점프합니다. 교활함, 점프
6 My Lazy Days of Summer 여름방학 동안 휴식을 취하는 것에 관한 짧은 이야기 여름, 휴식, 휴가, 태양

텍스트 하위 쿼리

텍스트 쿼리는 데이터 객체의 하나 이상의 필드와 일치합니다. 모든 구조화된 쿼리에는 하나 이상의 텍스트 쿼리가 포함되어야 합니다.

다음 예에서는 기본 텍스트 쿼리를 정의합니다.

"text_search": {
  "structured_query": {
    "text": {
      "text": "fox vs dog"
    }
  }
}

기본적으로 텍스트는 개별 용어로 분할되고 각 용어는 지정된 필드에서 검색됩니다. 위의 예에서는 Title 필드에서 'fox', 'vs', 'dog'이라는 용어를 검색합니다.

텍스트 쿼리에는 다음과 같은 선택적 매개변수가 있습니다.

  • fields: 일치시킬 필드의 배열입니다. 지정하지 않으면 모든 필드와 일치합니다. 필드는 암시적 OR 연산자와 일치합니다.

  • match_type: 실행할 일치 유형입니다. 검색 유형은 EXACT일 수 있으며, 이는 필드가 검색 텍스트와 정확히 일치해야 함을 지정합니다. 필드가 문자열 배열인 경우 배열의 요소에 대해 일치 여부가 확인됩니다.

  • enhancement: enabled 및 languageCode를 지정하여 languageCode에 지정된 언어 (예: en-US)의 동의어, 어간, 철자 오류, 불용어에 대해 일치를 실행할 수 있습니다. 기본값은 개선이 없습니다.

  • boost: 선택사항. 쿼리의 점수에 적용할 배수입니다. 기본값은 1.0입니다.

일치 유형

match_type 매개변수는 검색 텍스트가 필드의 값과 일치하는 방식을 지정합니다.

매개변수의 값은 다음 중 하나일 수 있습니다.

  • EXACT: 필드가 검색어와 정확히 일치해야 합니다. 필드가 문자열 배열인 경우 배열의 요소와 일치하는지 확인합니다.

다음 예에서는 EXACT 검색 유형을 지정합니다.

"text_search": {
  "structured_query": {
    "text": {
      "text": "Fox vs Dog",
      "fields": [ "Title" ],
      "match_type": "EXACT"
    }
  }
}

문자열 배열의 검색 유형

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
1.0000 3 여우 대 개 빠른 여우가 개를 속입니다. 야생, 가축, 갈등, 개아목, 포유류, 상호작용

필드가 문자열 배열인 경우 검색 텍스트는 배열 요소와 일치합니다.

다음 예시에서는 Keywords 문자열 배열에서 정확한 텍스트 wild를 검색하는 방법을 보여줍니다.

"text_search": {
  "structured_query": {
    "text": {
      "text": "wild",
      "fields": [ "Keywords" ],
      "match_type": "EXACT"
    }
  }
}

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
1.0000 3 여우 대 개 빠른 여우가 개를 속입니다. 야생, 가축, 갈등, 개아목, 포유류, 상호작용
1.0000 4 브라운 베어스 숲 속에서 빠르게 움직입니다. 야생, 숲, 곰, 최상위 포식자, 동면, 거대
1.0000 1 The Quick Brown Fox 빠른 갈색 여우가 게으른 개를 쉽게 뛰어넘습니다. 야생, 숲, 포유류, 주황색, 민첩성, 포식자

쿼리 개선사항

검색어에는 언어별 개선사항을 지정하는 선택적 queryEnhancement 매개변수가 포함될 수 있습니다. 여기에는 동의어, 어간('점프' 어간 '점핑' 등), 잘못된 맞춤법, 불용어('a', 'an', 'the' 등)에 대한 일치가 포함됩니다.

매개변수는 다음 속성이 있는 객체입니다.

  • enabled: 개선사항을 사용 설정할지 여부를 지정하는 불리언입니다.

  • languageCode: 개선사항의 언어를 지정하는 문자열입니다(예: en-US).

다음 예에서는 en-US 언어의 개선사항을 사용 설정합니다.

"text_search": {
  "structured_query": {
    "text": {
      "text": {
        "text": "jump",
        "fields": [ "Description" ],
        "queryEnhancement": {
          "enabled": true,
          "languageCode": "en-US"
        }
      }
    }
  }
}

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
0.3419 1 The Quick Brown Fox 빠른 갈색 여우가 게으른 개를 쉽게 뛰어넘습니다. 야생, 숲, 포유류, 주황색, 민첩성, 포식자
0.3419 5 여우 이야기 개가 높이 점프합니다. 교활함, 점프

queryEnhancement이 지정되지 않았거나 enabled이 false인 경우 일치하는 항목이 없습니다.

결합된 하위 쿼리

결합된 쿼리는 두 개 이상의 하위 쿼리에 불리언 연산을 적용합니다. 지원되는 작업은 AND 및 OR입니다.

결합된 쿼리에는 다음과 같은 속성이 있습니다.

  • op: 하위 쿼리에 적용할 불리언 연산자입니다. 값은 AND 또는 OR일 수 있습니다.

  • subQueries: 결합할 하위 쿼리의 배열입니다. 다른 결합된 쿼리를 포함하여 지원되는 하위 쿼리 유형이 될 수 있습니다. 최대 중첩 깊이는 2입니다.

    • boost: 선택사항. 쿼리의 점수에 적용할 배수입니다. 기본값은 1.0입니다.

접속사 (AND)

AND 연산자는 모든 하위 쿼리의 용어가 포함된 데이터 객체와 일치합니다.

다음 예는 AND 연산자를 사용하여 텍스트 쿼리 3개를 결합하는 방법을 보여줍니다.

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

이 예에서는 세 개의 하위 쿼리가 모두 일치하는 경우에만 일치가 이루어집니다.

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
5.0587 4 브라운 베어스 숲 속에서 빠르게 움직입니다. 야생, 숲, 곰, 최상위 포식자, 동면, 거대
5.0587 1 The Quick Brown Fox 빠른 갈색 여우가 게으른 개를 쉽게 뛰어넘습니다. 야생, 숲, 포유류, 주황색, 민첩성, 포식자

일치시킬 필드가 여러 개인 텍스트 하위 쿼리에는 다음 예와 같이 암시적 OR가 적용됩니다.

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title", "Description" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

앞의 예시를 다시 보겠습니다.

  • 첫 번째 하위 쿼리는 Title 또는 Description 필드에서 대소문자를 구분하지 않는 용어 Brown와 일치합니다.

  • 두 번째 하위 쿼리는 Description 필드에서 대소문자를 구분하지 않는 quick 용어와 일치합니다.

  • 세 번째 하위 쿼리는 Keywords 문자열 배열 필드의 값 중 하나에서 대소문자를 구분하지 않는 forest 및 predator 용어와 일치합니다.

  • 세 개의 하위 쿼리가 모두 일치하면 결합된 쿼리가 일치합니다.

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
6.3176 1 The Quick Brown Fox 빠른 갈색 여우가 게으른 개를 쉽게 뛰어넘습니다. 야생, 숲, 포유류, 주황색, 민첩성, 포식자
5.0587 4 브라운 베어스 숲 속에서 빠르게 움직입니다. 야생, 숲, 곰, 최상위 포식자, 동면, 거대

분리 (OR)

OR 연산자는 하위 쿼리 중 하나의 검색어가 포함된 데이터 객체와 일치합니다.

다음 예는 OR 연산자를 사용하여 텍스트 쿼리 3개를 결합하는 방법을 보여줍니다.

"text_search": {
  "structured_query": {
    "combine": {
      "op": "OR",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title", "Description" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

이 예에서는 세 개의 하위 쿼리 중 하나라도 일치하면 일치하는 것으로 간주됩니다.

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
6.3176 1 The Quick Brown Fox 빠른 갈색 여우가 게으른 개를 쉽게 뛰어넘습니다. 야생, 숲, 포유류, 주황색, 민첩성, 포식자
5.0587 4 브라운 베어스 숲 속에서 빠르게 움직입니다. 야생, 숲, 곰, 최상위 포식자, 동면, 거대

그룹화

평가 순서를 제어하기 위해 결합된 하위 쿼리를 다른 결합된 하위 쿼리 내에 중첩할 수 있습니다.

다음 예에서는 하위 쿼리를 그룹화하는 방법을 보여줍니다.

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "combine": {
            "op": "OR",
            "subQueries": [
              {
                "text": {
                  "text": "Fox",
                  "fields": [ "Title" ]
                }
              },
              {
                "text": {
                  "text": "jumps",
                  "fields": [ "Description" ]
                }
              }
            ]
          }
        },
        {
          "unary": {
            "op": "NOT",
            "subQuery": {
              "text": {
                "text": "domestic",
                "fields": [ "Keywords" ]
              }
            }
          }
        }
      ]
    }
  }
}

위의 예는 다음 표현식과 같습니다. (Title의 대소문자를 구분하지 않는 Fox OR Description의 대소문자를 구분하지 않는 jumps) AND NOT Keywords 요소의 대소문자를 구분하지 않는 domestic

다음 표는 쿼리 결과를 보여줍니다.

점수 ID 제목 설명 키워드
3.5178 1 The Quick Brown Fox 빠른 갈색 여우가 게으른 개를 쉽게 뛰어넘습니다. 야생, 숲, 포유류, 주황색, 민첩성, 포식자
2.2589 5 여우 이야기 개가 높이 점프합니다. 교활함, 점프

단항 서브 쿼리

단항 하위 쿼리는 구조화된 쿼리에서 단일 하위 쿼리에 불리언 연산을 적용합니다. NOT 연산자만 지원되는 단항 연산자입니다.

단항 쿼리에는 다음과 같은 속성이 있습니다.

  • op: 하위 쿼리에 적용할 불리언 연산자입니다. 값은 NOT일 수 있습니다.

  • subQuery: 단항 연산을 적용할 하위 쿼리입니다.

    • boost: 선택사항. 쿼리의 점수에 적용할 배수입니다. 기본값은 1.0입니다.

부정 (NOT)

NOT 연산자는 하위 쿼리의 용어가 포함되지 않은 데이터 객체를 찾습니다.

다음 예에서는 NOT 연산자를 사용하는 방법을 보여줍니다.

"text_search": {
  "structured_query": {
    "unary": {
      "op": "NOT",
      "subQuery": {
        "text": {
          "text": "dog",
          "fields": [ "Description" ]
        }
      }
    }
  }
}

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
1.000 4 브라운 베어스 숲 속에서 빠르게 움직입니다. 야생, 숲, 곰, 최상위 포식자, 동면, 거대
1.000 6 My Lazy Days of Summer 여름방학 동안 휴식을 취하는 것에 관한 짧은 이야기 여름, 휴식, 휴가, 태양

문자열 배열에 적용하면 NOT 연산자는 용어가 배열의 요소에 포함되지 않은 경우 데이터 객체와 일치합니다.

이 예에서는 대소문자를 구분하지 않는 용어 orange이 Keywords 문자열 배열의 어떤 요소에도 포함되지 않으면 일치합니다.

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        },
        {
          "unary": {
            "op": "NOT",
            "subQuery": {
              "text": {
                "text": "orange",
                "fields": [ "Keywords" ]
              }
            }
          }
        }
      ]
    }
  }
}

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
6.0587 4 브라운 베어스 숲 속에서 빠르게 움직입니다. 야생, 숲, 곰, 최상위 포식자, 동면, 거대

부스팅

모든 하위 쿼리에는 하위 쿼리의 점수에 승수를 적용하는 boost 매개변수가 있을 수 있습니다. 기본적으로 모든 하위 쿼리의 boost는 1.0입니다.

다음 예에서는 하위 쿼리를 부스팅하는 방법을 보여줍니다.

"text_search": {
  "structured_query": {
    "combine": {
      "op": "OR",
      "subQueries": [
        {
          "text": {
            "text": "fox",
            "fields": [ "Title" ]
          },
          "boost": 1.0
        },
        {
          "text": {
            "text": "jumps",
            "fields": [ "Description" ]
          },
          "boost": 1.0
        },
        {
          "text": {
            "text": "interaction",
            "fields": [ "Keywords" ]
          },
          "boost": 5.0
        }
      ]
    }
  }
}

쿼리 결과는 다음 표에 표시됩니다.

점수 ID 제목 설명 키워드
7.5534 3 여우 대 개 빠른 여우가 개를 속입니다. 야생, 가축, 갈등, 개아목, 포유류, 상호작용
2.5178 1 The Quick Brown Fox 빠른 갈색 여우가 게으른 개를 쉽게 뛰어넘습니다. 야생, 숲, 포유류, 주황색, 민첩성, 포식자
1.2589 5 여우 이야기 개가 높이 점프합니다. 교활함, 점프

이 검색은 텍스트 쿼리를 임베딩으로 변환하여 시맨틱 의미를 기반으로 결과를 찾습니다. 스키마에 정의된 embedding-config를 사용하여 쿼리 임베딩을 생성합니다. vector_search 필드가 여러 개 제공되면 동일한 가중치를 사용하여 결과가 결합됩니다.

batch_search_data_objects를 사용하여 벡터 검색, 텍스트 검색, 시맨틱 검색 등 여러 검색을 동시에 실행합니다. 결과는 선택적으로 ReciprocalRankFusion 순위 지정 도구를 사용하여 결합하고 순위를 지정할 수 있습니다. 이 도구는 Reciprocal Rank Fusion (RFF) 알고리즘을 사용하여 결과 세트를 병합합니다.