Classificar

Descrição

Classifica os documentos de entrada com base em uma ou mais ordenações especificadas.

Sintaxe

O exemplo a seguir classifica a coleção cities por population em ordem crescente:

Node.js

const results = await db.pipeline()
  .collection("/cities")
  .sort(Field.of("population").ascending())
  .execute();

O exemplo a seguir classifica a coleção cities pelo length do nome da cidade, em ordem crescente.

Node.js

const results = await db.pipeline()
  .collection("/cities")
  .sort(Field.of("name").charLength().ascending())
  .execute();

Exemplos de clientes

Web

const results = await execute(db.pipeline()
  .collection("books")
  .sort(
    field("release_date").descending(), field("author").ascending()
  )
);
test.firestore.js
Swift
let results = try await db.pipeline()
  .collection("books")
  .sort([
    Field("release_date").descending(), Field("author").ascending()
  ])
  .execute()
PipelineSnippets.swift

Kotlin

val results = db.pipeline()
    .collection("books")
    .sort(
        field("release_date").descending(),
        field("author").ascending()
    )
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> results = db.pipeline()
    .collection("books")
    .sort(
        field("release_date").descending(),
        field("author").ascending()
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

results = (
    client.pipeline()
    .collection("books")
    .sort(Field.of("release_date").descending(), Field.of("author").ascending())
    .execute()
)
firestore_pipelines.py
Java
Pipeline.Snapshot results =
    firestore
        .pipeline()
        .collection("books")
        .sort(descending(field("release_date")), ascending(field("author")))
        .execute()
        .get();
PipelineSnippets.java

Comportamento

Ordem de classificação

A ordem de classificação segue a ordem de tipo de valor de Cloud Firestore

Ordem determinista dos resultados

Se não houver uma etapa sort na consulta, a ordenação dos resultados retornados não será determinista e poderá variar entre as execuções. Se uma etapa sort estiver presente, mas as expressões de ordenação não produzirem uma ordenação exclusiva entre os resultados retornados, a ordenação dos resultados retornados ainda poderá variar entre as execuções.

Por exemplo, classificar cidades pelo country delas, em ordem crescente, em relação ao seguinte conjunto de dados

{name: 'Los Angeles', state: 'CA', country: 'USA', population: 3970000},
{name: 'New York', state: 'NY', country: 'USA', population: 8530000}
{name: 'San Francisco', state: 'CA', country: 'USA', population: 870000},

pode gerar qualquer permutação dos três documentos no conjunto de dados porque todos têm o mesmo atributo country. Para produzir uma ordenação determinística dos resultados, adicione uma ordem de classificação em name à ordem:

Node.js

const results = await db.pipeline()
  .collection("/cities")
  .sort(Field.of("country").ascending(), Field.of("__name__").ascending())
  .execute();

Isso vai usar o nome exclusivo do documento como critério de desempate quando vários documentos tiverem o mesmo valor de country. Outros campos que, junto com o campo country, formam uma chave exclusiva do documento na coleção podem ser usados para produzir uma ordem determinista de resultados.

Como classificar valores equivalentes

Valores equivalentes são classificados juntos, mas a ordem dos resultados na classe equivalente não é determinista, de acordo com a ordem determinista dos resultados. Por exemplo, classificar cidades por size, em ordem crescente, em relação ao seguinte conjunto de dados

{name: 'Los Angeles', state: 'CA', country: 'USA', size: 3970000},
{name: 'Mexico City', state: null, country: 'Mexico', size: 3970000.0},

pode produzir qualquer permutação dos dois documentos no conjunto de dados porque ambos têm o valor size equivalente 3970000.

Várias etapas de classificação

Quando a consulta contém várias etapas de classificação consecutivas, apenas a última etapa afeta os resultados. Isso é diferente do comportamento da cláusula orderBy na API principal.

Otimização da classificação Top-N

Quando um limit é usado após um sort, uma classificação de top-n pode ser usada. Essa otimização limita o uso de memória da etapa de classificação, permitindo que ela armazene apenas N documentos por vez, conforme definido por limit, tornando a classificação mais eficiente em termos de memória.

Valores nulos e ausentes

Se um campo especificado em uma ordenação não existir em um documento, o valor dele será classificado como se fosse null. Por exemplo, classificar cidades pelo state delas, em ordem crescente, em relação ao seguinte conjunto de dados

{name: 'Los Angeles', state: 'CA', country: 'USA', population: 3970000},
{name: 'Mexico City', state: null, country: 'Mexico', population: 9200000},
{name: 'New York', state: 'NY', country: 'USA', population: 8530000}
{name: 'San Francisco', state: 'CA', country: 'USA', population: 870000},
{name: 'Toronto', country: 'Canada', population: 2930000},

produz os seguintes resultados, em que os documentos "Toronto" e "Cidade do México" são classificados como null e antes de outros documentos.

{name: 'Toronto', country: 'Canada', population: 2930000},
{name: 'Mexico City', state: null, country: 'Mexico', population: 9200000},
{name: 'Los Angeles', state: 'CA', country: 'USA', population: 3970000},
{name: 'San Francisco', state: 'CA', country: 'USA', population: 870000},
{name: 'New York', state: 'NY', country: 'USA', population: 8530000}