|
1 | 1 | ---
|
2 | 2 | title: OFFSET LIMIT
|
3 | 3 | titleSuffix: Azure Cosmos DB for NoSQL
|
4 |
| -description: An Azure Cosmos DB for NoSQL query clause with two keywords that skips and/or takes a specified number of results. |
| 4 | +description: An Azure Cosmos DB for NoSQL clause that skips and takes a specified number of results. |
5 | 5 | author: jcodella
|
6 | 6 | ms.author: jacodel
|
7 | 7 | ms.reviewer: sidandrews
|
8 | 8 | ms.service: cosmos-db
|
9 | 9 | ms.subservice: nosql
|
10 | 10 | ms.topic: reference
|
11 | 11 | ms.devlang: nosql
|
12 |
| -ms.date: 07/08/2024 |
| 12 | +ms.date: 02/27/2024 |
13 | 13 | ms.custom: query-reference
|
14 | 14 | ---
|
15 | 15 |
|
16 | 16 | # OFFSET LIMIT (NoSQL query)
|
17 | 17 |
|
18 | 18 | [!INCLUDE[NoSQL](../../includes/appliesto-nosql.md)]
|
19 | 19 |
|
20 |
| -The `OFFSET LIMIT` clause is an optional clause to **skip** and then **take** some number of values from the query. The `OFFSET` count and the `LIMIT` count are required in the OFFSET LIMIT clause. |
| 20 | +The ``OFFSET LIMIT`` clause is an optional clause to **skip** and then **take** some number of values from the query. The ``OFFSET`` count and the ``LIMIT`` count are required in the OFFSET LIMIT clause. |
21 | 21 |
|
22 |
| -When `OFFSET LIMIT` is used with an `ORDER BY` clause, the result set is produced by doing skip and take on the ordered values. If no `ORDER BY` clause is used, it results in a deterministic order of values. |
| 22 | +When ``OFFSET LIMIT`` is used with an ``ORDER BY`` clause, the result set is produced by doing skip and take on the ordered values. If no ``ORDER BY`` clause is used, it results in a deterministic order of values. |
23 | 23 |
|
24 | 24 | ## Syntax
|
25 | 25 |
|
26 | 26 | ```nosql
|
27 | 27 | OFFSET <offset_amount> LIMIT <limit_amount>
|
28 |
| -``` |
| 28 | +``` |
29 | 29 |
|
30 | 30 | ## Arguments
|
31 | 31 |
|
32 | 32 | | | Description |
|
33 | 33 | | --- | --- |
|
34 |
| -| **`<offset_amount>`** | Specifies the integer number of items that the query results should skip. | |
35 |
| -| **`<limit_amount>`** | Specifies the integer number of items that the query results should include. | |
| 34 | +| **``<offset_amount>``** | Specifies the integer number of items that the query results should skip. | |
| 35 | +| **``<limit_amount>``** | Specifies the integer number of items that the query results should include. | |
36 | 36 |
|
37 | 37 | ## Examples
|
38 | 38 |
|
39 |
| -For the example in this section, this reference set of items is used. Each item includes a `name` property. |
| 39 | +For the example in this section, this reference set of items is used. Each item includes a ``name`` property. |
40 | 40 |
|
41 |
| -:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/offset-limit/seed.json" range="1-2,4-7,9-12,14-17,19-22,24-27" highlight="3,7,11,15,19"::: |
| 41 | +:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/offset-limit/seed.json" range="1-2,4-7,9-12,14-17,19-22,24-27" highlight="3,6,9,12,15"::: |
42 | 42 |
|
43 |
| -> [!NOTE] |
44 |
| -> In the original JSON data, the items are not sorted. |
45 |
| -
|
46 |
| -The first example includes a query that returns only the `name` property from all items sorted in alphabetical order. |
47 |
| - |
48 |
| -:::code language="nosql" source="~/cosmos-db-nosql-query-samples/scripts/offset-limit-none/query.sql"::: |
49 |
| - |
50 |
| -:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/offset-limit-none/result.json"::: |
51 |
| - |
52 |
| -This next example includes a query using the `OFFSET LIMIT` clause to skip the first item. The limit is set to the number of items in the container to return all possible remaining values. In this example, the query skips **one** item, and returns the remaining **four** (out of a limit of five). |
53 |
| - |
54 |
| -:::code language="nosql" source="~/cosmos-db-nosql-query-samples/scripts/offset-limit-partial/query.sql" highlight="10"::: |
55 |
| - |
56 |
| -:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/offset-limit-partial/result.json"::: |
57 |
| - |
58 |
| -This final example includes a query using the `OFFSET LIMIT` clause to return a subset of the matching items by skipping **one** item and taking the next **three**. |
| 43 | +This example includes a query using the ``OFFSET LIMIT`` clause to return a subset of the matching items by skipping **one** item and taking the next **three**. |
59 | 44 |
|
60 | 45 | :::code language="nosql" source="~/cosmos-db-nosql-query-samples/scripts/offset-limit/query.sql" highlight="10":::
|
61 | 46 |
|
62 | 47 | :::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/offset-limit/result.json":::
|
63 | 48 |
|
64 | 49 | ## Remarks
|
65 | 50 |
|
66 |
| -- Both the `OFFSET` count and the `LIMIT` count are required in the `OFFSET LIMIT` clause. If an optional `ORDER BY` clause is used, the result set is produced by doing the skip over the ordered values. Otherwise, the query returns a fixed order of values. |
67 |
| -- The RU charge of a query with `OFFSET LIMIT` increases as the number of terms being offset increases. For queries that have [multiple pages of results](pagination.md), we typically recommend using [continuation tokens](pagination.md#continuation-tokens). Continuation tokens are a "bookmark" for the place where the query can later resume. If you use `OFFSET LIMIT`, there's no "bookmark." If you wanted to return the query's next page, you would have to start from the beginning. |
68 |
| -- You should use `OFFSET LIMIT` for cases when you would like to skip items entirely and save client resources. For example, you should use `OFFSET LIMIT` if you want to skip to the 1000th query result and have no need to view results 1 through 999. On the backend, `OFFSET LIMIT` still loads each item, including those items that are skipped. The performance advantage is measured in reducing client resources by avoiding processing items that aren't needed. |
| 51 | +- Both the ``OFFSET`` count and the ``LIMIT`` count are required in the ``OFFSET LIMIT`` clause. If an optional ``ORDER BY`` clause is used, the result set is produced by doing the skip over the ordered values. Otherwise, the query returns a fixed order of values. |
| 52 | +- The RU charge of a query with ``OFFSET LIMIT`` increases as the number of terms being offset increases. For queries that have [multiple pages of results](pagination.md), we typically recommend using [continuation tokens](pagination.md#continuation-tokens). Continuation tokens are a "bookmark" for the place where the query can later resume. If you use ``OFFSET LIMIT``, there's no "bookmark." If you wanted to return the query's next page, you would have to start from the beginning. |
| 53 | +- You should use ``OFFSET LIMIT`` for cases when you would like to skip items entirely and save client resources. For example, you should use ``OFFSET LIMIT`` if you want to skip to the 1000th query result and have no need to view results 1 through 999. On the backend, ``OFFSET LIMIT`` still loads each item, including those items that are skipped. The performance advantage is measured in reducing client resources by avoiding processing items that aren't needed. |
69 | 54 |
|
70 | 55 | ## Related content
|
71 | 56 |
|
72 |
| -- [`GROUP BY` clause](group-by.md) |
73 |
| -- [`ORDER BY` clause](order-by.md) |
| 57 | +- [``GROUP BY`` clause](group-by.md) |
| 58 | +- [``ORDER BY`` clause](order-by.md) |
0 commit comments