Sort (Transformation Stage)

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. You can process personal data for this feature as outlined in theCloud Data Processing Addendum, subject to the obligations and restrictions described in the agreement under which you access Google Cloud. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Description

Sorts the input documents based on one or more specified sort orderings.

Syntax

The following example sorts thecities collection bypopulation in ascending order:

constresults=awaitdb.pipeline().collection("/cities").sort(Field.of("population").ascending()).execute();

The following example sorts thecities collection by thelength of the city name, in ascending order.

constresults=awaitdb.pipeline().collection("/cities").sort(Field.of("name").charLength().ascending()).execute();

Client examples

constresults=awaitexecute(db.pipeline().collection("books").sort(field("release_date").descending(),field("author").ascending()));
test.firestore.js

letresults=tryawaitdb.pipeline().collection("books").sort([Field("release_date").descending(),Field("author").ascending()]).execute()
PipelineSnippets.swift

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

Task<Pipeline.Snapshot>results=db.pipeline().collection("books").sort(field("release_date").descending(),field("author").ascending()).execute();
DocSnippets.java

fromgoogle.cloud.firestore_v1.pipeline_expressionsimportFieldresults=(client.pipeline().collection("books").sort(Field.of("release_date").descending(),Field.of("author").ascending()).execute())
firestore_pipelines.py

Pipeline.Snapshotresults=firestore.pipeline().collection("books").sort(descending(field("release_date")),ascending(field("author"))).execute().get();
PipelineSnippets.java

Behavior

Sort order

Sort order followsFirestore's value type order

Deterministic Order of Results

If there is nosort stage in the query, the ordering of the returned results is non-deterministic and may vary between executions. If asort stage is present but the ordering expressions fail to produce a unique ordering among the returned results, the ordering of the returned results may still vary between executions.

For example, sorting cities by thecountry of the cities, in ascending order against the following dataset

{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},

can produce any permutation of the 3 documents in the dataset because they all have the samecountry attribute.To produce a deterministic ordering of the results, you can append a sort order onname to the order:

constresults=awaitdb.pipeline().collection("/cities").sort(Field.of("country").ascending(),Field.of("__name__").ascending()).execute();

This will use the unique document name as the tiebreaker when multiple documents have the samecountry value.Note that any other fields which together with thecountry field form a unique key of the document within the collection can be used to produce a deterministic order of results.

Sorting Equivalent Values

Equivalent values are sorted together but the order of results within the equivalent class are not deterministic according to theDeterministic Order of Results discussion.For example, sorting cities bysize, in ascending order against the following dataset

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

can produce any permutation of the 2 documents in the dataset because both documents have the equivalentsize value3970000.

Multiple Sort Stages

When the query contains multiple consecutive sort stages, only the last sort stage has an impact on the query results. Note that this is different from the behavior of theorderBy clause in the Core API.

Top-N Sort Optimization

When alimit is used after asort, a top-n sort may be used. This optimization bounds the memory use of the sort stage by allowing it to only storeN documents at a time—as defined bylimit—making the sort more memory-efficient.

Null and Absent values

If a field specified in an ordering does not exist in a document, its value is sorted as if the value isnull.For example, sorting cities by thestate of the cities, in ascending order against the following dataset

{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},

produces the following results where the "Toronto" document and the "Mexico City" document are sorted asnull and before other documents.

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