Como consultar coleções de objetos de dados

O objetivo da API Query é recuperar objetos de dados de uma coleção usando um filtro. Isso é semelhante a consultar uma tabela de banco de dados e usar uma cláusula SQL WHERE. Você também pode usar a agregação para receber uma contagem de objetos de dados que correspondem a um filtro.

Linguagem de expressão de filtro

Além da funcionalidade de pesquisa KNN/ANN, a Pesquisa de vetor 2.0 oferece recursos de consulta versáteis usando uma linguagem de consulta personalizada. A linguagem de consulta é explicada na tabela a seguir.

Filtro Descrição Tipos compatíveis Exemplo
$eq Corresponde a objetos de dados com valores de campo iguais a um valor especificado. Número, string, booleano {"genre": {"$eq": "documentary"}}
$ne Corresponde a objetos de dados com valores de campo que não são iguais a um valor especificado. Número, string, booleano {"genre": {"$ne": "drama"}}
$gt Corresponde a objetos de dados com valores de campo maiores que um valor especificado. Número {"year": {"$gt": 2019}}
$gte Faz correspondência com objetos de dados com valores de campo maiores ou iguais a um valor especificado. Número {"year": {"$gte": 2020}}
$lt Corresponde a objetos de dados com valores de campo menores que um valor especificado. Número {"year": {"$lt": 2020}}
$lte Faz correspondência com objetos de dados que têm valores de campo menores ou iguais a um valor especificado. Número {"year": {"$lte": 2020}}
$in Corresponde a objetos de dados com valores de campo que estão em uma matriz especificada. String {"genre": {"$in": ["comedy", "documentary"]}}
$nin Corresponde a objetos de dados com valores de campo que não estão em uma matriz especificada. String {"genre": {"$nin": ["comedy", "documentary"]}}
$and Combina cláusulas de consulta com um AND lógico. - {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$or Combina cláusulas de consulta com um OR lógico. - {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$all Seleciona os documentos em que o valor da matriz de um campo contém todos os valores especificados. - {"colors": {"$all": ["red", "blue"]}}

Consultar coleções

O exemplo a seguir demonstra como usar um filtro para consultar objetos de dados em uma coleção com o ID COLLECTION_ID.

REST

# Query Data Objects
curl -X POST \
'https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H 'Content-Type: application/json' \
  -d '{
    "page_size": 10,
    "page_token": "",
    "filter": {
      "$or": [
        {
          "director": {
            "$eq": "Akira Kurosawa"
          }
        },
        {
          "$and": [
            {
              "director": {
                "$eq": "David Fincher"
              }
            },
            {
              "genre": {
                "$ne": "Thriller"
              }
            }
          ]
        }
      ]
    },
    "output_fields": {
      "data_fields": "*",
      "vector_fields": "*",
      "metadata_fields": "*"
    }
  }'

Python

from google.cloud import vectorsearch_v1beta

# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.QueryDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    filter={
        "$or": [
            {"director": {"$eq": "Akira Kurosawa"}},
            {
                "$and": [
                    {"director": {"$eq": "David Fincher"}},
                    {"genre": {"$ne": "Thriller"}},
                ]
            },
        ]
    },
)

# Make the request
page_result = data_object_search_service_client.query_data_objects(request=request)

# Handle the response
for response in page_result:
    print(response)

Para realizar uma agregação, use o endpoint aggregate e especifique o tipo de agregação no corpo da solicitação.

O exemplo a seguir demonstra como contar todos os objetos de dados em uma coleção com o ID COLLECTION_ID.

REST

curl -X POST \
'https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H 'Content-Type: application/json' \
  -d '{
    "aggregate": "count"
  }'

Python

from google.cloud import vectorsearch_v1beta

# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.AggregateDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    aggregate="COUNT",
)

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

# Handle the response
print(response)

A seguir