Skip to content

RDoc-3779 + RDoc-3848 Control order of NULLs in query results #2454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ppekrol merged 5 commits into from
May 29, 2026
Merged

RDoc-3779 + RDoc-3848 Control order of NULLs in query results #2454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cb1bc7f
RDoc-3779 "what is RQL" + "indexing configuration"
Danielle9897 May 19, 2026
b12eb6d
RDoc-3779 The "sort query results" article
Danielle9897 May 19, 2026
a50fe9c
RDoc-3779 The "spatial query" article
Danielle9897 May 20, 2026
5ca7f63
RDoc-3858 Sort query results: Add performance notes & Metadata example
Danielle9897 May 20, 2026
dff4a84
RDoc-3858 fix review comments
Danielle9897 May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
430 changes: 274 additions & 156 deletions docs/client-api/session/querying/content/_how-to-make-a-spatial-query-csharp.mdx
View file
Open in desktop

Large diffs are not rendered by default.

18 changes: 9 additions & 9 deletions docs/client-api/session/querying/content/_how-to-make-a-spatial-query-nodejs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import CodeBlock from '@theme/CodeBlock';

* When making a dynamic spatial query from Studio,
results are also displayed on the global map. See [spatial queries map view](../../../../studio/database/queries/spatial-queries-map-view.mdx).
* In this page:
* In this article:

* [Search by radius](../../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius)
* [Search by shape](../../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape)
Expand Down Expand Up @@ -383,7 +383,7 @@ const metadata = session.advanced.getMetadataFor(employeesSortedByDistance[0]);
const spatialResults = metadata["@spatial"];

const distance = spatialResults.Distance; // The distance of the entity from the queried location
const latitude = spatialResults.Latitude; // The entity's longitude value
const latitude = spatialResults.Latitude; // The entity's latitude value
const longitude = spatialResults.Longitude; // The entity's longitude value
`}
</CodeBlock>
Expand Down Expand Up @@ -501,13 +501,13 @@ orderByDistanceDescending(fieldName, shapeWkt);
</CodeBlock>
</TabItem>

| Parameter | Type | Description |
|------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| __fieldName__ | `string` | Path to spatial field in index<br/>(when querying an index). |
| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,<br/>either `PointField` or `WktField`<br/>(when making a dynamic query). |
| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. |
| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured |
| __roundFactor__ | `number` | A distance interval in kilometers.<br/>The distance from the point is rounded up to the nearest interval.<br/>The results within the same interval can be sorted by a secondary order.<br/>If no other order was specified, then by ascending order of document Id. |
| Parameter | Type | Description
|------------------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| __fieldName__ | `string` | Path to spatial field in index<br/>(when querying an index). |
| __field__ | `DynamicSpatialField` | Object that contains the document's spatial fields,<br/>either `PointField` or `WktField`<br/>(when making a dynamic query). |
| __shapeWkt__ | `string` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape to be used as a point from which distance will be measured. If the shape is not a single point, then the center of the shape will be used as a reference. |
| __latitude__ / __longitude__ | `number` | Used to define a point from which distance will be measured |
| __roundFactor__ | `number` | A distance interval in kilometers.<br/>The distance from the point is rounded up to the nearest interval.<br/>Use `orderBy` to apply a secondary sort to results within the same distance interval. |



Expand Down
4 changes: 2 additions & 2 deletions docs/client-api/session/querying/content/_how-to-make-a-spatial-query-python.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import CodeBlock from '@theme/CodeBlock';

* When making a dynamic spatial query from Studio,
results are also displayed on the global map. See [spatial queries map view](../../../../studio/database/queries/spatial-queries-map-view.mdx).
* In this page:
* In this article:

* [Search by radius](../../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-radius)
* [Search by shape](../../../../client-api/session/querying/how-to-make-a-spatial-query.mdx#search-by-shape)
Expand Down Expand Up @@ -529,7 +529,7 @@ def order_by_distance_descending_wkt(
| **field_or_field_name** | `Union[str, DynamicSpatialField]` | `Str` - Path to spatial field in an index (when querying an index)<br/><br/>**-or-**<br/><br/>`DynamicSpatialField` - Object that contains the document's spatial fields, either `PointField` or `WktField`(when making a dynamic query). |
| **latitude** | `float` | The latitude of the point from which the distance is measured |
| **longitude** | `float` | The longitude of the point from which the distance is measured |
| **round_factor** (Optional) | `float` | A distance interval in kilometers.<br/>The distance from the point is rounded up to the nearest interval.<br/>The results within the same interval can be sorted by a secondary order.<br/>If no other order was specified, then by ascending order of document Id. |
| **round_factor** (Optional) | `float` | A distance interval in kilometers.<br/>The distance from the point is rounded up to the nearest interval.<br/>Use `order_by` to apply a secondary sort to results within the same distance interval. |
| **shape_wkt** | `str` | [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)-based shape used in query criteria |


Expand Down
111 changes: 107 additions & 4 deletions docs/querying/rql/what-is-rql.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,11 @@ import ContentFrame from "@site/src/components/ContentFrame";
* Using the session's [RawQuery](../../querying/overview.mdx#session-advanced-rawquery) method in the Client API.
* Writing a query in the [Query view](../../studio/database/queries/query-view.mdx) in Studio, where [RQL code assistance](../../querying/rql/rql-code-assistance.mdx) is available.

* **RQL keywords are case-insensitive**:
For example, `SELECT`, `select`, and `Select` are equivalent.

---

* In this article:
* [The query pipeline](../../querying/rql/what-is-rql.mdx#the-query-pipeline)
* [RQL keywords and methods](../../querying/rql/what-is-rql.mdx#rql-keywords-and-methods)
Expand Down Expand Up @@ -132,10 +137,10 @@ The following keywords and methods are available in RQL:
- [long](../../querying/sorting-query-results/sort-query-results.mdx)
- [double](../../querying/sorting-query-results/sort-query-results.mdx)
- [alphaNumeric](../../querying/sorting-query-results/sort-query-results.mdx)
- [NULLS FIRST | NULLS LAST](../../querying/sorting-query-results/sort-query-results.mdx) // TODO...
- [random()](../../querying/sorting-query-results/sort-query-results.mdx#order-by-random)
- [score()](../../querying/sorting-query-results/sort-query-results.mdx#order-by-score)
- [spatial.distance()](../../client-api/session/querying/how-to-make-a-spatial-query.mdx#spatial-sorting)
- [LOAD](../../querying/rql/what-is-rql.mdx#load)
- [SELECT](../../querying/rql/what-is-rql.mdx#select)
- DISTINCT
- key()
Expand All @@ -144,6 +149,7 @@ The following keywords and methods are available in RQL:
- [facet()](../../indexes/querying/faceted-search.mdx)
- [timeseries()](../../document-extensions/timeseries/querying/overview-and-syntax.mdx#syntax)
- [counter()](../../document-extensions/counters/counters-and-other-features.mdx#counters-and-queries)
- [LOAD](../../querying/rql/what-is-rql.mdx#load)
- [LIMIT](../../querying/rql/what-is-rql.mdx#limit)
- [UPDATE](../../querying/rql/what-is-rql.mdx#update)
- [INCLUDE](../../querying/rql/what-is-rql.mdx#include)
Expand Down Expand Up @@ -494,9 +500,106 @@ The keyword `include` has been introduced to support:

## `order by`

Use `order by` to perform sorting.
Learn more in this [sorting](../../querying/sorting-query-results/sort-query-results.mdx) article.
Use `order by` to sort the query results by one or more fields.
Learn more about sorting in the [Sort query results](../../querying/sorting-query-results/sort-query-results.mdx) article.

RQL syntax:

<TabItem>
```sql
ORDER BY <expression> [AS <type>] [ASC | DESC] [NULLS FIRST | NULLS LAST]
```
</TabItem>

By default, results are sorted in ascending order.

<TabItem>
```sql
from "Employees"
order by FirstName // ascending order
```
</TabItem>

To specify the sort direction, add `asc`, `ascending`, `desc`, or `descending`.

<TabItem>
```sql
from "Employees"
order by FirstName desc // descending order
```
</TabItem>

You can also specify the sort type by adding `as <type>`.
<TabItem>
```sql
from "Products"
order by UnitsInStock as long desc
```
</TabItem>

Use `nulls first` or `nulls last` to control where matching documents with `null` or missing values in the sorted field will appear in the query results.
This is supported only by the [Corax](../../indexes/search-engine/corax.mdx) search engine.

The `nulls first` and `nulls last` options are absolute.
They place those documents before or after matching documents with non-null values, regardless of whether the query sorts in ascending or descending order:

* `nulls first` places those documents **before** matching documents with non-null values.
* `nulls last` places those documents **after** matching documents with non-null values.

<TabItem>
```csharp
// Place documents whose ReportsTo field is null (or missing) at the top of the results
from "Employees"
order by ReportsTo nulls first
```
</TabItem>

<TabItem>
```csharp
// Cast + direction + null placement on a single key
from "Products"
order by UnitsInStock as long desc nulls last
```
</TabItem>

<TabItem>
```csharp
// Works with method expressions
from "Employees"
order by id() as string nulls last
```
</TabItem>

<TabItem>
```csharp
// Works with spatial sorting
from "Employees"
order by spatial.distance(Address.Location, spatial.point(0, 0)) nulls first
```
</TabItem>

<TabItem>
```csharp
// Per-clause control on a multi-key sort.
// Each clause sets its own null placement.
from "Products"
order by Name nulls first,
UnitsInStock desc, // omitted: uses default
PricePerUnit as double nulls last
```
</TabItem>


<Admonition type="info" title="">

* If `nulls first` / `nulls last` is Not specified, RavenDB uses the configured default behavior.
See [Indexing.Querying.Corax.NullsSortMode](../../server/configuration/indexing-configuration.mdx#indexingqueryingcoraxnullssortmode).

* The `nulls first` / `nulls last` clause is supported only by the [Corax](../../indexes/search-engine/corax.mdx) search engine.
Issuing a query that contains this clause against a Lucene index will return an `InvalidQueryException`.

</Admonition>

---

## `select`
Expand All @@ -508,7 +611,7 @@ Learn more in this [projection](../../indexes/querying/projections.mdx) article.

## `load`

Use `load`when you need to use data from a related document in projection.
Use `load` when you need to use data from a related document in projection.
See an example in this [projection](../../indexes/querying/projections.mdx#example-viii---projection-using-a-loaded-document) article.

---
Expand Down
Loading
Loading