Pesquisar objetos de dados

O objetivo da API Search é encontrar objetos de dados semelhantes a uma consulta específica e retornar uma lista de resultados classificados por similaridade. A API Search também oferece suporte à filtragem.

A API Search oferece várias maneiras de pesquisar objetos de dados: pesquisa vetorial, pesquisa de texto completo e pesquisa semântica. Além disso, várias pesquisas de qualquer tipo podem ser combinadas para realizar uma pesquisa híbrida.

Com a pesquisa vetorial, você pode fornecer seu próprio vetor de consulta. Esse é o método obrigatório para pesquisar campos de incorporação que não têm um embedding-config. Se vários campos vector_search forem fornecidos, os resultados serão combinados usando ponderações iguais.

O exemplo a seguir demonstra como realizar uma pesquisa vetorial em uma coleção com o ID COLLECTION_ID.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • COLLECTION_ID: o ID da coleção.
  • LOCATION: A região em que você está usando o Agent Platform.
  • PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{
  "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": "*"
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SEARCH_VECTOR_FILE: o caminho local para um arquivo JSON que contém o vetor denso ou esparso para pesquisar.

    Exemplo de conteúdo do arquivo para um vetor denso:

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

    Exemplo de conteúdo do arquivo para um vetor esparso:

    {
  "sparse": {
    "indices": [1, 5, 10],
    "values": [0.1, 0.5, 0.21]
  }
}
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: A região em que você está usando o Agent Platform.
  • PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .

Execute o seguinte comando:

Linux, macOS ou 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

Você receberá uma resposta semelhante a esta:

---
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)

Ajustar a precisão e o desempenho da pesquisa

Para pesquisas de vetor em índices ANN densos com mais de 100.000 embeddings, a recuperação de agente, por padrão, tenta oferecer uma troca ideal entre recall e latência. É possível ajustar esse equilíbrio para seu caso de uso especificando uma taxa de recall desejada.

Os valores precisam ser maiores ou iguais a 0.00 e menores ou iguais a 1.00.

Para saber como criar um índice ANN, acesse Criar um índice ANN.

O exemplo a seguir demonstra como realizar uma pesquisa vetorial em um índice ANN denso com uma taxa de recall de destino de 0.95.

REST

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "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

Salve o vetor de consulta em um arquivo JSON, por exemplo, vector.json:

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

Em seguida, execute o comando 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)

Pesquisa de texto

Isso realiza uma pesquisa de texto completo sem vetores esparsos. O dialeto padrão de consulta "word" trata toda a entrada como termos de pesquisa individuais com um operador AND implícito. Você pode definir enhanced_query como true para expandir os termos de pesquisa, processar a derivação, remover palavras irrelevantes e permitir outros operadores de pesquisa:

  • OR: um operador de disjunção que diferencia maiúsculas de minúsculas e corresponde a documentos que contêm pelo menos um dos termos especificados. Isso se aplica apenas aos dois termos adjacentes.

  • ": (aspas duplas) para pesquisa de frases.

  • -: o operador de negação. Ele exclui documentos que contêm termos que aparecem antes dele.

Pesquisa de texto avançada

Com a API de pesquisa de texto de recuperação de agente, você pode expressar pesquisas de texto usando consultas estruturadas que contêm uma ou mais subconsultas. Assim, é possível:

  • Fazer correspondência com campos específicos de objetos de dados.

  • Especifique o tipo de correspondência a ser realizada:

    • Por termo, não diferencia maiúsculas de minúsculas

    • Exatamente, diferencia maiúsculas de minúsculas

  • Inclua melhorias por idioma para corresponder a radicais de termos, sinônimos, erros de ortografia e palavras de parada (como "um", "uma" e "o").

  • Use os operadores booleanos AND, OR e NOT para combinar subconsultas.

  • Controle a ordem de avaliação agrupando subconsultas.

  • Aumentar as contribuições de pontuação para influenciar as classificações.

Há três tipos de subconsultas:

  • Texto: fornece o texto de pesquisa e um ou mais campos para correspondência.

  • Unário: aplica uma operação NOT a uma única subconsulta.

  • Combinado: aplica o operador AND ou OR para combinar subconsultas e pode ser usado para agrupar outras subconsultas combinadas e controlar a ordem de avaliação.

Os exemplos nesta página usam a coleção demonstrada na tabela a seguir. Ele contém seis objetos de dados e define os seguintes campos no esquema de dados: as strings ID, Title, Description e a matriz de strings Keywords.

ID Título Descrição Palavras-chave
1 A raposa-parda rápida Uma rápida raposa marrom pula facilmente sobre o cachorro preguiçoso. selvagem, floresta, mamífero, laranja, agilidade, predador
2 Dias de preguiça O cachorro marrom dorme. doméstico, animal de estimação, casa, canino, calmo, preguiçoso, obediente
3 Raposa x cachorro A raposa esperta engana o cachorro. selvagem, doméstico, conflito, caniformes, mamíferos, interação
4 Ursos-pardos Movimentos rápidos na floresta. selvagem, floresta, ursino, predador de ponta, hibernação, gigante
5 Uma história esperta O cachorro pula alto. astuto, pula
6 Meus dias de verão Uma história curta sobre relaxar durante as férias de verão. verão, relaxar, férias, sol

Subconsultas de texto

As consultas de texto correspondem a um ou mais campos em um objeto de dados. Todas as consultas estruturadas precisam conter pelo menos uma consulta de texto.

O exemplo a seguir define uma consulta de texto básica:

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

Por padrão, o texto é dividido em termos individuais, e cada termo é pesquisado nos campos especificados. No exemplo anterior, os termos "fox", "vs" e "dog" são pesquisados no campo Title.

As consultas de texto têm os seguintes parâmetros opcionais:

  • fields: uma matriz de campos para corresponder. Se não for especificado, o padrão será corresponder a todos os campos. Os campos são correspondidos com um operador OR implícito.

  • match_type: o tipo de correspondência a ser realizada. O tipo de correspondência pode ser EXACT, que especifica que o campo precisa corresponder exatamente ao texto de pesquisa. Se o campo for uma matriz de strings, uma correspondência será feita com qualquer elemento na matriz.

  • enhancement: especifica enabled e um languageCode, permitindo que as correspondências sejam feitas com sinônimos, radicais, erros de ortografia e palavras irrelevantes no idioma especificado para languageCode (por exemplo, en-US). O padrão é sem melhoria.

  • boost: opcional. Um multiplicador a ser aplicado à pontuação da consulta. O padrão é 1.0.

Tipo de correspondência

O parâmetro match_type especifica como o texto de pesquisa corresponde ao valor de um campo.

O valor do parâmetro pode ser:

  • EXACT: o campo precisa corresponder exatamente ao termo de consulta. Se o campo for uma matriz de strings, uma correspondência será feita com qualquer elemento da matriz.

O exemplo a seguir especifica o tipo de correspondência EXACT:

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

Tipo de correspondência para matrizes de strings

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
1,0000 3 Raposa x cachorro A raposa esperta engana o cachorro. selvagem, doméstico, conflito, caniformes, mamíferos, interação

Quando o campo é uma matriz de strings, o texto de pesquisa é comparado com qualquer elemento da matriz.

O exemplo a seguir mostra como pesquisar o texto exato wild na matriz de strings Keywords:

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

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
1,0000 3 Raposa x cachorro A raposa esperta engana o cachorro. selvagem, doméstico, conflito, caniformes, mamíferos, interação
1,0000 4 Ursos-pardos Movimentos rápidos na floresta. selvagem, floresta, ursino, predador de ponta, hibernação, gigante
1,0000 1 A raposa-parda rápida Uma rápida raposa marrom pula facilmente sobre o cachorro preguiçoso. selvagem, floresta, mamífero, laranja, agilidade, predador

Melhorias nas consultas

As consultas de pesquisa podem incluir um parâmetro queryEnhancement opcional para especificar melhorias específicas do idioma. Isso inclui correspondências com sinônimos, radicais (por exemplo, o radical "pulo" e "pulando"), grafias incorretas e palavras de parada (como "um", "uma" e "o").

O parâmetro é um objeto com as seguintes propriedades:

  • enabled: um booleano que especifica se as melhorias serão ativadas.

  • languageCode: uma string que especifica o idioma das melhorias (por exemplo, en-US).

O exemplo a seguir ativa as melhorias para o idioma en-US:

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

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
0,3419 1 A raposa-parda rápida Uma rápida raposa marrom pula facilmente sobre o cachorro preguiçoso. selvagem, floresta, mamífero, laranja, agilidade, predador
0,3419 5 Uma história esperta O cachorro pula alto. astuto, pula

Se queryEnhancement não foi especificado ou enabled foi false, nenhuma correspondência será feita.

Subconsultas combinadas

As consultas combinadas aplicam uma operação booleana a duas ou mais subconsultas. As operações aceitas são AND e OR.

As consultas combinadas têm as seguintes propriedades:

  • op: o operador booleano a ser aplicado às subconsultas. O valor pode ser AND ou OR.

  • subQueries: uma matriz de subconsultas a serem combinadas. Elas podem ser qualquer um dos tipos de subconsultas compatíveis, incluindo outras consultas combinadas. A profundidade máxima de aninhamento é 2.

    • boost: opcional. Um multiplicador a ser aplicado à pontuação da consulta. O padrão é 1.0.

Conjunção (AND)

O operador AND corresponde a objetos de dados que contêm os termos de todas as subconsultas.

O exemplo a seguir demonstra como combinar três consultas de texto usando o operador AND:

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

No exemplo, as correspondências só são feitas se todas as três subconsultas corresponderem.

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
5,0587 4 Ursos-pardos Movimentos rápidos na floresta. selvagem, floresta, ursino, predador de ponta, hibernação, gigante
5,0587 1 A raposa-parda rápida Uma rápida raposa marrom pula facilmente sobre o cachorro preguiçoso. selvagem, floresta, mamífero, laranja, agilidade, predador

Quando uma subconsulta de texto tem vários campos para corresponder, um OR implícito é aplicado, como mostrado no exemplo a seguir:

"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" ]
          }
        }
      ]
    }
  }
}

No exemplo anterior:

  • A primeira subconsulta corresponde ao termo Brown, que não diferencia maiúsculas de minúsculas, no campo Title ou Description.

  • A segunda subconsulta corresponde ao termo quick no campo Description, sem diferenciar maiúsculas de minúsculas.

  • A terceira subconsulta corresponde aos termos forest e predator, que não diferenciam maiúsculas de minúsculas, em qualquer um dos valores no campo de matriz de strings Keywords.

  • Se todas as três subconsultas corresponderem, uma correspondência será feita na consulta combinada.

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
6.3176 1 A raposa-parda rápida Uma rápida raposa marrom pula facilmente sobre o cachorro preguiçoso. selvagem, floresta, mamífero, laranja, agilidade, predador
5,0587 4 Ursos-pardos Movimentos rápidos na floresta. selvagem, floresta, ursino, predador de ponta, hibernação, gigante

Disjunção (OR)

O operador OR corresponde a objetos de dados que contêm os termos de pelo menos uma das subconsultas.

O exemplo a seguir demonstra como combinar três consultas de texto usando o operador OR:

"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" ]
          }
        }
      ]
    }
  }
}

No exemplo, uma correspondência é feita se alguma das três subconsultas corresponder.

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
6.3176 1 A raposa-parda rápida Uma rápida raposa marrom pula facilmente sobre o cachorro preguiçoso. selvagem, floresta, mamífero, laranja, agilidade, predador
5,0587 4 Ursos-pardos Movimentos rápidos na floresta. selvagem, floresta, ursino, predador de ponta, hibernação, gigante

Agrupamento

As subconsultas combinadas podem ser aninhadas em outras subconsultas combinadas para controlar a ordem de avaliação.

O exemplo a seguir mostra como agrupar subconsultas:

"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" ]
              }
            }
          }
        }
      ]
    }
  }
}

O exemplo anterior é equivalente a: (Fox sem diferenciação de maiúsculas e minúsculas em Title OR jumps sem diferenciação de maiúsculas e minúsculas em Description) AND NOT domestic sem diferenciação de maiúsculas e minúsculas em qualquer um dos elementos Keywords.

A tabela a seguir mostra os resultados da consulta:

Pontuação ID Título Descrição Palavras-chave
3,5178 1 A raposa-parda rápida Uma rápida raposa marrom pula facilmente sobre o cachorro preguiçoso. selvagem, floresta, mamífero, laranja, agilidade, predador
2,2589 5 Uma história esperta O cachorro pula alto. astuto, pula

Subconsultas unárias

As subconsultas unárias aplicam uma operação booleana a uma única subconsulta em uma consulta estruturada. O operador NOT é a única operação unária compatível.

As consultas unárias têm as seguintes propriedades:

  • op: o operador booleano a ser aplicado à subconsulta. O valor pode ser NOT.

  • subQuery: a subconsulta a que a operação unária será aplicada.

    • boost: opcional. Um multiplicador a ser aplicado à pontuação da consulta. O padrão é 1.0.

Negação (NOT)

O operador NOT corresponde a objetos de dados que não contêm os termos da subconsulta.

O exemplo a seguir demonstra como usar o operador NOT:

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

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
1.000 4 Ursos-pardos Movimentos rápidos na floresta. selvagem, floresta, ursino, predador de ponta, hibernação, gigante
1.000 6 Meus dias de verão Uma história curta sobre relaxar durante as férias de verão. verão, relaxar, férias, sol

Quando aplicado a uma matriz de strings, o operador NOT corresponde a um objeto de dados se o termo não estiver contido em nenhum dos elementos da matriz.

No exemplo, uma correspondência será feita se o termo orange, que não diferencia maiúsculas de minúsculas, não estiver contido em nenhum elemento da matriz de strings 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" ]
              }
            }
          }
        }
      ]
    }
  }
}

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
6,0587 4 Ursos-pardos Movimentos rápidos na floresta. selvagem, floresta, ursino, predador de ponta, hibernação, gigante

Otimização

Qualquer subconsulta pode ter um parâmetro boost para aplicar um multiplicador à pontuação da subconsulta. Por padrão, todas as subconsultas têm um boost de 1.0.

O exemplo a seguir demonstra como aumentar uma subconsulta:

"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
        }
      ]
    }
  }
}

Os resultados da consulta são mostrados na tabela a seguir:

Pontuação ID Título Descrição Palavras-chave
7,5534 3 Raposa x cachorro A raposa esperta engana o cachorro. selvagem, doméstico, conflito, caniformes, mamíferos, interação
2,5178 1 A raposa-parda rápida Uma rápida raposa marrom pula facilmente sobre o cachorro preguiçoso. selvagem, floresta, mamífero, laranja, agilidade, predador
1,2589 5 Uma história esperta O cachorro pula alto. astuto, pula

Essa pesquisa converte sua consulta de texto em embeddings para encontrar resultados com base no significado semântico. Ele usa o embedding-config definido no seu esquema para gerar o embedding de consulta. Se vários campos vector_search forem fornecidos, os resultados serão combinados usando ponderações iguais.

Use batch_search_data_objects para executar várias pesquisas em paralelo (vetorial, de texto e pesquisa semântica). Os resultados podem ser combinados e classificados usando o classificador ReciprocalRankFusion, que mescla conjuntos de resultados usando o algoritmo Reciprocal Rank Fusion (RFF).