StructuredQuery

Uma consulta do Firestore.

Os estágios da consulta são executados na seguinte ordem: 1. de 2, em que 3. selecione 4. orderBy + startAt + endAt 5. desvio 6. limit.

Representação JSON 
{
  "select": {
    object (Projection)
  },
  "from": [
    {
      object (CollectionSelector)
    }
  ],
  "where": {
    object (Filter)
  },
  "orderBy": [
    {
      object (Order)
    }
  ],
  "startAt": {
    object (Cursor)
  },
  "endAt": {
    object (Cursor)
  },
  "offset": integer,
  "limit": integer,
  "findNearest": {
    object (FindNearest)
  }
}
Campos
select

object (Projection)

Subconjunto opcional dos campos a serem retornados.

Isso funciona como um DocumentMask nos documentos retornados de uma consulta. Quando não definido, presume que o autor da chamada quer que todos os campos sejam retornados.
from[]

object (CollectionSelector)

As coleções a serem consultadas.
where

object (Filter)

O filtro que será aplicado.
orderBy[]

object (Order)

A ordem a ser aplicada aos resultados da consulta.

O Firestore permite que os autores de chamadas forneçam uma ordem completa, uma ordem parcial ou nenhuma ordem. Em todos os casos, o Firestore garante uma ordem estável por meio das seguintes regras:

  • O orderBy é obrigatório para referenciar todos os campos usados com um filtro de desigualdade.
  • Todos os campos que precisam estar no orderBy, mas que ainda não estão presentes, são anexados na ordem lexicográfica do nome do campo.
  • Se um pedido em __name__ não for especificado, ele será anexado por padrão.

Campos são anexados com a mesma direção de classificação que a última ordem especificada, ou 'ASCENDING' caso nenhum pedido tenha sido especificado. Exemplo:

  • ORDER BY a agora é ORDER BY a ASC, __name__ ASC
  • ORDER BY a DESC se torna ORDER BY a DESC, __name__ DESC
  • WHERE a > 1 agora é WHERE a > 1 ORDER BY a ASC, __name__ ASC
  • WHERE __name__ > ... AND a > 1 se torna WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
startAt

object (Cursor)

Um possível prefixo de uma posição no conjunto de resultados em que a consulta será iniciada.

A ordem do conjunto de resultados é baseada na cláusula ORDER BY da consulta original.

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

Os resultados desta consulta são ordenados por (b ASC, __name__ ASC).

Os cursores podem fazer referência à ordem completa ou a um prefixo do local, mas não podem fazer referência a mais campos do que o ORDER BY fornecido.

Continuando com o exemplo acima, anexar os seguintes cursores de início terá um impacto variável:

  • START BEFORE (2, /k/123): inicia a consulta logo antes de a = 1 AND b > 2 AND __name__ > /k/123.
  • START AFTER (10): inicia a consulta logo após a = 1 AND b > 10.

Ao contrário de OFFSET, que exige a verificação dos primeiros N resultados para pular, um cursor de início permite que a consulta comece em uma posição lógica. Essa posição não precisa corresponder a um resultado real, ela vai avançar dessa posição para encontrar o próximo documento.

Requer:

  • O número de valores não pode ser maior que o número de campos especificado na cláusula ORDER BY.
endAt

object (Cursor)

Um possível prefixo de uma posição no conjunto de resultados em que a consulta será encerrada.

Isso é semelhante à START_AT, mas controla a posição final, e não a inicial.

Requer:

  • O número de valores não pode ser maior que o número de campos especificado na cláusula ORDER BY.
offset

integer

O número de documentos a serem ignorados antes de retornar o primeiro resultado.

Isso se aplica depois das restrições especificadas por WHERE, START AT e END AT, mas antes da cláusula LIMIT.

Requer:

  • Se especificado, o valor precisa ser maior ou igual a zero.
limit

integer

O número máximo de resultados a serem retornados.

Aplica-se após todas as outras restrições.

Requer:

  • Se especificado, o valor precisa ser maior ou igual a zero.
findNearest

object (FindNearest)

Opcional. Uma pesquisa sobre vizinhos mais próximos em potencial.

Aplica-se depois de todos os outros filtros e ordenação.

Encontra os embeddings de vetor mais próximos do vetor de consulta especificado.

Projeção

A projeção dos campos do documento a serem retornados.

Representação JSON 
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
Campos
fields[]

object (FieldReference)

Os campos a serem retornados.

Se estiver vazio, todos os campos serão retornados. Para retornar apenas o nome do documento, use ['__name__'].

Seletor de coleção

Uma seleção de uma coleção, como messages as m1.

Representação JSON 
{
  "collectionId": string,
  "allDescendants": boolean
}
Campos
collectionId

string

O ID da coleção. Quando definido, seleciona apenas coleções com esse ID.
allDescendants

boolean

Quando falso, seleciona apenas os conjuntos que são filhos imediatos do parent especificado no RunQueryRequest. Quando verdadeiro, seleciona todas as coleções descendentes.

Filtro

Um filtro.

Representação JSON 
{

  // Union field filter_type can be only one of the following:
  "compositeFilter": {
    object (CompositeFilter)
  },
  "fieldFilter": {
    object (FieldFilter)
  },
  "unaryFilter": {
    object (UnaryFilter)
  }
  // End of list of possible types for union field filter_type.
}
Campos
Campo de união filter_type. O tipo de filtro. filter_type pode ser apenas de um dos tipos a seguir:
compositeFilter

object (CompositeFilter)

Um filtro composto.
fieldFilter

object (FieldFilter)

Um filtro em um campo do documento.
unaryFilter

object (UnaryFilter)

Um filtro que usa exatamente um argumento.

CompositeFilter

Um filtro que combina vários outros usando o operador especificado.

Representação JSON 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
Campos
op

enum (Operator)

O operador para combinar vários filtros.
filters[]

object (Filter)

A lista de filtros a serem combinados.

Requer:

  • Pelo menos um filtro está presente.

Operador

Um operador de filtro composto.

Enums
OPERATOR_UNSPECIFIED Não especificado. Não use esse valor.
AND Os documentos precisam atender a todos os filtros combinados.
OR Os documentos precisam atender a pelo menos um dos filtros combinados.

Filtrodecampo

Um filtro em um campo específico.

Representação JSON 
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
Campos
field

object (FieldReference)

O campo a ser filtrado.
op

enum (Operator)

O operador a ser filtrado.
value

object (Value)

O valor a ser comparado.

Operador

Um operador de filtro de campo.

Enums
OPERATOR_UNSPECIFIED Não especificado. Não use esse valor.
LESS_THAN

O field informado é menor que o value.

Requer:

  • Esse field ficou em primeiro lugar em orderBy.
LESS_THAN_OR_EQUAL

O field informado é menor ou igual ao value informado.

Requer:

  • Esse field ficou em primeiro lugar em orderBy.
GREATER_THAN

O field informado é maior que o value.

Requer:

  • Esse field ficou em primeiro lugar em orderBy.
GREATER_THAN_OR_EQUAL

A field especificada é maior ou igual à value especificada.

Requer:

  • Esse field ficou em primeiro lugar em orderBy.
EQUAL O field informado é igual ao value informado.
NOT_EQUAL

O field informado não é igual ao value informado.

Requer:

  • Nenhum outro NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Esse field vem em primeiro lugar no orderBy.
ARRAY_CONTAINS O field é uma matriz que contém o value especificado.
IN

A field especificada é igual a pelo menos um valor na matriz em questão.

Requer:

  • Esse value é um ArrayValue não vazio, sujeito a limites de disjunção.
  • Não há filtros NOT_IN na mesma consulta.
ARRAY_CONTAINS_ANY

A field especificada é uma matriz que contém qualquer um dos valores da matriz em questão.

Requer:

  • Esse value é um ArrayValue não vazio, sujeito a limites de disjunção.
  • Nenhum outro filtro ARRAY_CONTAINS_ANY na mesma disjunção.
  • Não há filtros NOT_IN na mesma consulta.
NOT_IN

O valor de field não está na matriz em questão.

Requer:

  • Esse value é um ArrayValue não vazio com no máximo 10 valores.
  • Nenhum outro OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL ou IS_NOT_NAN.
  • Esse field vem em primeiro lugar no orderBy.

Filtro Unário

Um filtro com um único operando.

Representação JSON 
{
  "op": enum (Operator),

  // Union field operand_type can be only one of the following:
  "field": {
    object (FieldReference)
  }
  // End of list of possible types for union field operand_type.
}
Campos
op

enum (Operator)

O operador unário a ser aplicado.
Campo de união operand_type. O argumento para o filtro. operand_type pode ser apenas de um dos tipos a seguir:
field

object (FieldReference)

O campo ao qual aplicar o operador.

Operador

Um operador unário.

Enums
OPERATOR_UNSPECIFIED Não especificado. Não use esse valor.
IS_NAN O field fornecido é igual a NaN.
IS_NULL O field fornecido é igual a NULL.
IS_NOT_NAN

O field fornecido não é igual a NaN.

Requer:

  • Nenhum outro NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Esse field vem em primeiro lugar no orderBy.
IS_NOT_NULL

O field fornecido não é igual a NULL.

Requer:

  • Um único NOT_EQUAL, NOT_IN, IS_NOT_NULL ou IS_NOT_NAN.
  • Esse field vem em primeiro lugar no orderBy.

Pedido

Um pedido em um campo.

Representação JSON 
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
Campos
field

object (FieldReference)

O campo pelo qual ordenar.
direction

enum (Direction)

A direção pela qual ordenar. O valor padrão é ASCENDING.

Direção

Uma direção de classificação.

Enums
DIRECTION_UNSPECIFIED Não especificado.
ASCENDING Crescente.
DESCENDING Decrescente.

Encontrar mais próximo

Configuração de pesquisa de vizinhos mais próximos.

Representação JSON 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
Campos
vectorField

object (FieldReference)

Obrigatório. Um campo de vetor indexado para pesquisar. Somente documentos com vetores com dimensionalidade correspondente ao queryVector podem ser retornados.
queryVector

object (Value)

Obrigatório. O vetor de consulta que estamos pesquisando. Precisa ser um vetor com no máximo 2.048 dimensões.
distanceMeasure

enum (DistanceMeasure)

Obrigatório. A medida de distância a ser usada, obrigatória.
limit

integer

Obrigatório. O número de vizinhos mais próximos a serem retornados. Precisa ser um número inteiro positivo de até 1.000.

Medida de distância

A medida de distância a ser usada na comparação de vetores.

Enums
DISTANCE_MEASURE_UNSPECIFIED Não deve ser definido.
EUCLIDEAN Mede a distância EUCLIDEAN entre os vetores. Consulte Euclidiano para saber mais
COSINE Compara vetores com base no ângulo entre eles, o que permite medir a similaridade que não é baseada na magnitude dos vetores. Recomendamos usar DOT_PRODUCT com vetores normalizados de unidade em vez da distância COSINE, que é matematicamente equivalente a um desempenho melhor. Consulte Semelhança de cossenos para saber mais.
DOT_PRODUCT Semelhante ao cosseno, mas é afetado pela magnitude dos vetores. Consulte Dot Product para saber mais.