MongoDB time-series query execution: bucket unpacking, pushdown, block processing and sorts

Parent: Global AI Hub Research Corpus · Published reference · snapshot 2026-10-19

Time series collections use [zstd](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-zstd) compression, which differs from the global default compression algorithm, [snappy.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-snappy) (from www.mongodb.com)

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

Definitions

For more information on running database commands from the C# Driver, refer to the [Run a Database Command](https://www.mongodb.com/docs/drivers/csharp/current/run-command/) page in the Node.js Driver documentation. [source]
For more information on running database commands from the Java Driver, refer to the [Run a Database Command](https://www.mongodb.com/docs/drivers/java/sync/current/command/) page in the Java Driver documentation. [source]
For more information on running database commands from the Node.js Driver, refer to the [Run a Database Command](https://www.mongodb.com/docs/drivers/node/current/run-command/) page in the Node.js Driver documentation. [source]
For more information on running database commands from the Java Driver, refer to the [Run a Database Command](https://www.mongodb.com/docs/languages/python/pymongo-driver/current/run-command/) page in the PyMongo Driver documentation. [source]
If an index uses prefix compression (which is the [`default for WiredTiger`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--wiredTigerIndexPrefixCompression)), the returned size reflects the compressed size. [source]
Time series data is a sequence of data points in which insights are gained by analyzing changes over time. [source]

Structure and components

In a regular collection, data is stored sequentially as blocks on disk, optimizing write speed. However, it requires one index for each data point, which quickly grows very large. It also requires a second index that contains the time series identifier and timestamps themselves, so that users can query for a single series. To read this data, MongoDB has to process all of the database and disk blocks that contain it, even if a block only contains a single relevant document. [source]
Each document you insert should contain a single measurement. To insert multiple documents at once, use the [`db.collection.insertMany()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertmany.md#mongodb-method-db.collection.insertMany) method: [source]
Before any metadata compaction, the `ESC` and `ECOC` contain one metadata document for every field/value pair of every indexed field. Indexing one encrypted field/value pair across 1000 documents requires 1000 documents in the `ESC` and 1000 documents in the `ECOC`. [source]
| Database Tool Name | Description | | --- | --- | | `list-databases` | Displays all databases available in your MongoDB deployment with their storage sizes. | | `list-collections` | Shows all collections within a specific database. | | `find` | Retrieves actual documents from a collection that match specific search criteria. | | `count` | Quickly returns the total number of documents in a collection without retrieving the documents themselves. | | `aggregate` | Performs complex data processing operations like grouping, filtering, transforming, and calculating statstics across documents. | | ` [source]
| Field | Necessity | Description | | --- | --- | --- | | [field](https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify.md#std-label-densify-field) | Required | The field to densify. The values of the specified `field` must either be all numeric values or all dates. Documents that do not contain the specified `field` continue through the pipeline unmodified. To specify a `<field>` in an embedded document or in an array, use [dot notation.](https://www.mongodb.com/docs/manual/core/document.md#std-label-document-dot-notation) For restrictions, see [`field` Restrictions.](htt [source]
The following example shows the `stocks` time series collection structure used in this quick start. [source]
The result document contains a document for the time series collection which contains the `options.expireAfterSeconds` field. [source]
This page shows how to create and query a time series collection. The code examples provided create and work with sample weather data that contains time, temperature, and sensor information. [source]
| Field Name | Data Type | Description | | --- | --- | --- | | `ns` | string | Namespace of the sharded collection. | | `shards` | array | Shards in the collection with the data distribution information for each shard. | | `shards.numOrphanedDocs` | integer | Number of orphaned documents in the shard. For [time series collections](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), `numOrphanedDocs` contains the number of orphaned measurement buckets in the shard. | | `shards.numOwnedDocuments` | integer | Number of documents owned by the [source]

How it works

Working set is the subset of data and indexes touched in a typical window, rarely the whole database. Practitioner guidance is to size the cache to working set plus write headroom, and to use a sustained post-warmup page-fault rate as a proxy when the size is unknown. [source]
During 8.0 development, Jira SERVER-88316 (fixed in 8.0.0-rc0) showed the server using block processing for a GroupByNull test case with only featureFlagSbeFull set, when the test expected none. This shows the block-processing decision depended on several feature flags. [source]
- In [time series collections](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), documents do not require a unique [\_id](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-_id) field because MongoDB does not create an index on the `_id` field. [source]
In time series collections, documents do not require a unique _id field because MongoDB does not create an index on the _id field. [source]
When you run `$collStats` on a time series collection with the `storageStats: {}` option, the output includes time series data. [source]
[`timeseries`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.timeseries) appears when you run the `collStats` command on a [time series collection.](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection) [source]
When migrating or backfilling into a time series collection, always insert the documents in order, from oldest to newest. In this case, [`mongodump`](https://www.mongodb.com/docs/database-tools/mongodump.md#mongodb-binary-bin.mongodump) exports documents in natural order and the `--maintainInsertionOrder` option for [`mongorestore`](https://www.mongodb.com/docs/database-tools/mongorestore.md#mongodb-binary-bin.mongorestore) guarantees the same insertion order for documents. [source]
When you create a [time series collection](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), you can set up automatic removal of documents older than a specified number of seconds by using the `expireAfterSeconds` property: [source]
When you create a [time series collection](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), you can set up automatic removal of documents older than a specified number of seconds by using the `expireAfterSeconds` parameter: [source]
Time series collections efficiently store time series data. Writes are organized so that data from the same source is stored alongside other data points from a similar point in time. [source]
When the collection you specify to [`sh.shardCollection()`](https://www.mongodb.com/docs/manual/reference/method/sh.shardcollection.md#mongodb-method-sh.shardCollection) is a time series collection, you do not need to specify the [timeseries](https://www.mongodb.com/docs/manual/reference/method/sh.shardcollection.md#std-label-method-sharded-time-series-collection-options) option. [source]

How-to and procedures

Use the [`shardCollection()`](https://www.mongodb.com/docs/manual/reference/method/sh.shardcollection.md#mongodb-method-sh.shardCollection) method with the [timeseries](https://www.mongodb.com/docs/manual/reference/method/sh.shardcollection.md#std-label-method-sharded-time-series-collection-options) option. [source]
Enable sharding on your collection by creating an index that supports the [shard key.](https://www.mongodb.com/docs/manual/core/sharding-shard-key.md#std-label-shard-key) [source]
Run the following command to create a hashed index on the `metadata.location` field: [source]
To shard a time series collection, you must [deploy a sharded cluster](https://www.mongodb.com/docs/manual/tutorial/deploy-shard-cluster.md#std-label-sharding-procedure-setup) to host the database that contains your time series collection. [source]
To learn more about the fields returned in the `timeseries: {}` document, see [bucketCatalog.](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#std-label-server-status-bucketcatalog) [source]
Create your collection with your desired time series settings using the [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createcollection.md#mongodb-method-db.createCollection) method. [source]
To run the complete aggregation pipeline to migrate the data into the new time series collection, call one of the methods that implements `IEnumerable`, such as `ToList`, `ToArray`, or `ToEnumerable` on the pipeline object. The following example shows the complete aggregation pipeline, including this final step: [source]
Add an [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) aggregation stage to your pipeline to create a time series collection and insert your data into it. The pipeline below performs the following operations: [source]
Run the complete aggregation pipeline to migrate the data into the new time series collection. [source]
Use the following steps to migrate data from an existing collection to a time series collection with [`mongodump`](https://www.mongodb.com/docs/database-tools/mongodump.md#mongodb-binary-bin.mongodump) and [`mongorestore`.](https://www.mongodb.com/docs/database-tools/mongorestore.md#mongodb-binary-bin.mongorestore) [source]
To create a new [time series collection](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), issue the following command in the [`mongosh`:](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) [source]
To export your data from an existing collection that is not of type `timeseries` use [`mongodump`.](https://www.mongodb.com/docs/database-tools/mongodump.md#mongodb-binary-bin.mongodump) [source]
To import your data into a timeseries collection, use [`mongorestore`.](https://www.mongodb.com/docs/database-tools/mongorestore.md#mongodb-binary-bin.mongorestore) [source]
To enable automatic removal of documents on a [time series collection](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection) that doesn't have an expiration, or to modify the expiration time on an existing collection, change the `expireAfterSeconds` parameter value, using the [`collMod`](https://www.mongodb.com/docs/manual/reference/command/collmod.md#mongodb-dbcommand-dbcmd.collMod) command: [source]
To retrieve the current value of `expireAfterSeconds`, use the `ListCollectionsAsync` method. The result document contains the `options.expireAfterSeconds` field for the timeseries collection. [source]
To retrieve the current value of `expireAfterSeconds`, use the `listCollections` method. The result document contains the `options.expireAfterSeconds` field for the timeseries collection. [source]
To enable automatic removal of documents for an existing [time series collection](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), issue the following [`collMod`](https://www.mongodb.com/docs/manual/reference/command/collmod.md#mongodb-dbcommand-dbcmd.collMod) command: [source]
To retrieve the current value of `expireAfterSeconds`, use the `list_collections` method. The result document contains the `options.expireAfterSeconds` field for the timeseries collection. [source]
To return one document from a time series collection, you use a [FilterDefinitionBuilder\<TDocument>](|api-root|/MongoDB.Driver/MongoDB.Driver.FilterDefinitionBuilder-1.html) to create a filter to match a document. You pass the filter to the `Find()` method of the `IMongoCollection<TDocument>` class. The following example creates a FilterDefinition and also uses a ProjectionDefinition to omit the `_id` field from the results. It returns a `List<BsonDocument>`. [source]
To return one document from a time series collection, you can use the `findOne()` method. This returns a [cursor.](https://www.mongodb.com/docs/manual/core/cursors.md#std-label-cursors) [source]
To return one document from a time series collection, you can use the `findOne()` method. The following example uses the `projection` field in the query to omit the `_id` field from the returned documents: [source]
To return one document from a time series collection, you can use the `find_one()` method. This returns a [cursor.](https://www.mongodb.com/docs/manual/core/cursors.md#std-label-cursors) [source]
To return one document from a time series collection, you can use the [`db.collection.findOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findone.md#mongodb-method-db.collection.findOne) method. The following example uses the `projection` field in the query to omit the `_id` field from the returned documents: [source]
Create and Query a Time Series Collection [source]
To list all time series collections in a database, use the [`listCollections`](https://www.mongodb.com/docs/manual/reference/command/listcollections.md#mongodb-dbcommand-dbcmd.listCollections) command with a filter for `{ type: "timeseries" }`: [source]
To automatically delete old data, [set up automatic removal (TTL).](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-automatic-removal.md#std-label-set-up-automatic-removal) [source]
Use the following pages to create and configure your time series collections. [source]
Use this tutorial to shard a new or existing time series collection. [source]

Examples and snippets

```java — `// Create an aggregation pipeline` … [source]
```javascript — `const pipeline = [` … [source]
```python — `pipeline = [` … [source]
```javascript — `db.weather.aggregate( [` … [source]
```javascript — `"ns" : <string>,` … [source]
```javascript — `db.weather.aggregate( [` … [source]
```javascript — `_id: ObjectId("<object-id>"),` … [source]
```javascript — `bucketsNs: 'test.weather',` … [source]
```csharp — `var query =` … [source]
```java — `Date target = Date.from(Instant.parse("2045-11-19T18:00:00Z"));` … [source]
```javascript — `catalogStats: {` … [source]
```json — `"cursor": {` … [source]
```javascript — `db.runCommand( {` … [source]
```javascript — `db.dowJonesTickerData.aggregate( [ {` … [source]
```python — `pipeline_results = stocks_coll.aggregate(` … [source]
```java — `// Create the compound _id with $dateTrunc and symbol` … [source]
```javascript — `const pipeline = [` … [source]
```none — `$dateTrunc: {` … [source]
```javascript — `db.cakeSales.aggregate( [` … [source]
```javascript — `db.cakeSales.aggregate( [` … [source]

Measurements and reference values

A MongoDB staff forum answer (March 2022) gave an informal rule of thumb of RAM at 15-20% of total data size, covering indexes, working set, queries and OS. It is not an official time-series formula and cites MongoDB 4.0 docs. [source]
A forum report with indexes on t/c in both directions shows a range filter { c: x, t: { $lte: ... } } with sort { t: -1 } spending IXSCAN ~4s but FETCH ~2-5 minutes, while a similar $gte ascending query took ~1s; no answer was given, version unstated. [source]
The maximum size for documents within a time series collection is 4 MB. [source]

Problems, failure modes and limitations

MongoDB automatically enables block processing for eligible time series queries. You cannot manually specify whether a query uses block processing. To see if your time series query uses block processing, see [`stages`](https://www.mongodb.com/docs/manual/reference/explain-results.md#mongodb-data-explain.queryPlanner.winningPlan.slotBasedPlan.stages) in the explain plan output. [source]
To check whether a query used block processing, inspect explain output at queryPlanner.winningPlan.slotBasedPlan.stages. A slotBasedPlan field means SBE ran the query. Slow-query logs carry a queryFramework field with value sbe or classic. The docs show no example of what block-processing stages look like. [source]
Block processing is automatic. Users cannot enable or disable it for a single query. Eligibility is decided per query, and queries with unsupported operators or expressions run on the classic engine. SBE support is version specific and still changing. [source]
Default WiredTiger internal cache is the larger of 50% of (RAM - 1 GB) or 256 MB. MongoDB advises against raising it above the default, and in containers it must be set below the container's RAM limit. [source]
Undersized-cache signals per one monitoring vendor: sustained fill above ~80% with rising eviction rates, dirty ratio above 15% (warning) or 20% (critical), and application-thread evictions. These thresholds are vendor heuristics, not MongoDB documentation. [source]
You cannot run sharding administration commands on sharded time series collections. [source]
| Field | Type | Description | | --- | --- | --- | | `distanceField` | string | The output field that contains the calculated distance. To specify a field within an embedded document, use [dot notation.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) This field is required for queries on timeseries collections. Starting in MongoDB 8.1, `distanceField` is optional for queries on non-timeseries collections. | | `distanceMultiplier` | number | Optional. The factor to multiply all distances returned by the query. For example, use the `distanceMultiplier` to conver [source]
For time series collections, TTL indexes also remove a bucket of data when all documents inside it expire. This is equal to the upper timestamp limit of the bucket, plus the `expireAfterSeconds` value. For example, if a bucket covers data up until `2023-03-27T18:29:59Z` and `expireAfterSeconds` is 300, the TTL index expires the bucket after `2023-03-27T18:34:59Z`. [source]
Ensure that you run the `mongorestore` command with the [`--noIndexRestore`](https://www.mongodb.com/docs/database-tools/mongorestore.md#std-option-mongorestore.--noIndexRestore) option. `mongorestore` cannot create indexes on time series collections. [source]
Starting in MongoDB 8.3, creating an index with the name of `"_id_"` or specifying a hint of `"_id_"` on time series collections returns an error. [source]
If you specify a modification in the `timeseries` parameter of your `collMod` operation, you cannot use other modification options in the same command. You must perform time series modifications in a dedicated command that is separate from other collection modifications. [source]
If MongoDB cannot obtain the sort order with an index scan, then MongoDB uses a top-k sort algorithm. This algorithm buffers the first `k` results (or last, depending on the sort order) seen so far by the underlying index or collection access. If the memory footprint of these `k` results exceeds 100 megabytes, MongoDB automatically writes temporary files to disk unless the query specifies [`cursor.allowDiskUse()`](https://www.mongodb.com/docs/manual/reference/method/cursor.allowdiskuse.md#mongodb-method-cursor.allowDiskUse) with a value of `false` (in which case, the query fails). [source]
Limits the amount of memory that simultaneous [index builds](https://www.mongodb.com/docs/manual/core/index-creation.md#std-label-index-build-process) on one collection may consume for their duration. The specified amount of memory is shared between all indexes built using a single [`createIndexes`](https://www.mongodb.com/docs/manual/reference/command/createindexes.md#mongodb-dbcommand-dbcmd.createIndexes) command or its shell helper [`db.collection.createIndexes()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.createindexes.md#mongodb-method-db.collection.createIndexes) [source]
Rolling indexes build indexes on the applicable nodes sequentially and may reduce the performance impact of an index build if your deployment's average CPU utilization exceeds (N-1)/N-10% where N is the number of CPU threads available to mongod of if the WiredTiger cache fill ratio regularly exceeds 90%. If your deployment does not meet this criteria, use the default index build. You can't create a rolling index on an M0 free cluster or M2/M5 shared cluster. [source]
You can't use the `query` field for `$geoNear` on a [time series collection.](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-landing) [source]
You cannot use the [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) aggregation stage to add data from another collection to a time series collection. [source]
| `$out` | [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) | | --- | --- | | Can output to a collection in the same or different database. | Can output to a collection in the same or different database. | | Creates a new collection if the output collection does not already exist. | Creates a new collection if the output collection does not already exist. | | Replaces the output collection completely if it already exists. | Can incorporate results (insert new documents, merge documents, replace documents, keep existing documen [source]
You cannot create a time series collection as a [capped collection.](https://www.mongodb.com/docs/manual/core/capped-collections.md#std-label-manual-capped-collection) [source]
- You cannot convert an existing collection into a time series collection. [source]
- You cannot convert a time series collection into a different collection type. [source]
You cannot write to time series collections in [transactions.](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions) [source]
If the time between the end of the to-be-rolledback instance's oplog and the first operation after the common point (the last point where the source node and the to-be-rolledback node had the same data) exceeds this value, the rollback will fail. [source]

Comparisons and alternatives

MongoDB's blog (published 2024-12-09, updated 2025-07-21) claims 10-40x improvements across workloads, up to 100x for some large aggregations, and 20x ops/sec versus 7.0 in a worked example. The example ran on an Atlas M50 using MongoDB's TSBS fork: about 6 million events, a 24-hour $match, $sort, $group with $dateTrunc, $setWindowFields and $expMovingAvg. [source]
Delta Encoding takes advantage of the data in your time series collection having time-series characteristics. Instead of storing absolute values, Delta Encoding assumes that the measurements will not change rapidly between each other. This approach reduces the amount of information required by only storing the difference between measurements. [source]
Starting in version 8.0, MongoDB may execute certain time series queries using block processing. This performance improvement processes queries in "blocks" of data, rather than individual values. Block processing improves query execution speed and throughput when working with time series collections. [source]
Time series collections use [zstd](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-zstd) compression, which differs from the global default compression algorithm, [snappy.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-snappy) [source]
MongoDB does not create an index on the `_id` field when you create a time series collection. This differs from regular collections which have an index on the `_id` field by default. Commands that specify a hint on the `_id` field on time series collections return an error unless you manually create an index on the `_id` field. [source]
Allegro's 5.0.3 benchmark found aggregation over a random six-hour window 23-48% faster on a time series collection than a regular one (10K to 100K queries), but single-timestamp lookups were nearly equal (16.854s vs 16.038s for 1M queries). [source]

Facts and statements

Starting in MongoDB 8.0, if a query uses [block processing](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-querying.md#std-label-timeseries-querying-block-processing), `block_to_row` and `ts_bucket_to_cellblock` appear in the `stages` output. [source]
The SBE reference page says SBE is disabled automatically on collections that have an index with a hashed-field prefix followed by a non-hashed field, with both fields in the index. Ineligible queries fall back to the classic engine. The page does not tie this rule to time series specifically. [source]
Collection data in the WiredTiger cache is uncompressed, so block compression saves disk but not cache space; the OS filesystem cache holds the compressed on-disk form. Indexes in cache still benefit from prefix compression. Compressed time series storage size therefore understates the cache footprint of hot buckets. [source]
MongoDB's docs state a bucket holds at most 1000 measurements or 125 KiB, whichever is lower, and MongoDB may enforce a lower maximum for high-cardinality data so the working set of buckets fits in the WiredTiger cache. [source]
Connect [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) to the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) for your sharded cluster. Specify the `host` and `port` on which the `mongos` is running: [source]
- Shards a new time series collection named `weather` on the `test` database. [source]
This page describes how MongoDB compresses data in time series collections, and how you can optimize compression. [source]
Starting in MongoDB 5.2, time series collections use **column compression**. Column compression adds a number of innovations that work together to significantly improve practical compression, reduce your data's overall storage on disk, and improve read performance. [source]
This weather data time series collection deletes documents after 24 hours: [source]
**Note: In-progress Indexes** [source]
The returned `storageStats` includes information about indexes being built. For details, see: [source]
This is distinct from using the [`index`](https://www.mongodb.com/docs/manual/reference/command/collmod.md#mongodb-collflag-index) option with the `expireAfterSeconds` property to change the expiration time for a [TTL Collection.](https://www.mongodb.com/docs/manual/tutorial/expire-data.md#std-label-ttl-collections) [source]
- `TS_MODIFY` for modifying a time series collection [source]
For operations on time series collections, the type of operation. [source]
For operations on time series collections, the number of buckets unpacked to resolve the operation. [source]
For operations on time series collections, the number of documents deleted. [source]
For operations on time series collections, the number of documents inserted. [source]
For operations on time series collections, the number of documents matched. [source]
For operations on time series collections, the number of documents modified. [source]
For operations on time series collections, the number of documents upserted. [source]
3. Create a hashed index on your collection. [source]
Zone sharding does not support time series collections. The balancer always distributes data in sharded time series collections evenly across all shards in the cluster. [source]
- To shard a time series collection, see [Shard a Time Series Collection.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-shard-collection.md#std-label-manual-timeseries-shard-collection) [source]
> Derived 2026-10-19; topic-filtered subset of mongodb.com-docs-query.md: Server manual pages about queries, indexes, aggregation, time series, profiling, explain, parameters and 7.x–9.0 release notes, plus Compass query/explain/index pages and Atlas performance/query pages. Third-party text; private reading aid; never publish. [source]
- Data is indexed by time and an identifier, such as a stock ticker, that identifies the unique time series it belongs to. [source]
- On a [time series collections](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-time-series-collection), you can only specify hints using the index name, not the index key pattern. [source]
```javascript 2021-06-01T16:50:56.639+0200 checking for collection data in timeseries/weather/temporarytimeseries.bson 2021-06-01T16:50:56.640+0200 restoring to existing collection weather.weathernew without dropping 2021-06-01T16:50:56.640+0200 reading metadata for weather.weathernew from timeseries/weather/temporarytimeseries.metadata.json 2021-06-01T16:50:56.640+0200 restoring weather.weathernew from timeseries/weather/temporarytimeseries.bson 2021-06-01T16:51:01.229+0200 no indexes to restore 2021-06-01T16:51:01.229+0200 finished restoring weather.weathernew (10000 documents, 0 failu [source]
In the following output, the [`$densify`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify.md#mongodb-pipeline-pipe.-densify) stage fills in the gaps of time between the hours of `00:00:00` and `08:00:00`. [source]
This model is optimized for [CRUD](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-CRUD) operations and frequent updates. A bank account balance only needs to reflect the current state, so each account holder's document is updated as that information changes. [source]
| Industry | Examples | | --- | --- | | Internet of Things (IoT) | Sensor data (for example, smart home devices or fleet logistics); Machine learning and artificial intelligence scraping | | Financial Services | High frequency trading; Financial quantitative analysis; Banking data (for example, accounting of banking transactions over time); Stock market data | | Retail and E-Commerce | Transaction, sales, and price analysis; Inventory management | | DevOps | Application logging; Infrastructure and network monitoring | [source]
The following example creates a database named `timeseries` and stores a reference to it under `timeSeriesDB`. It then create a timeseries collection named `weather` in that database and stores a reference to it under the same name: [source]
The following example uses a database named `timeseries` and stores a reference to it under `timeSeriesDB`. It then create a timeseries collection named `weather` in that database and stores a reference to it under the same name: [source]
For additional query functionality, you can use the `Aggregate()` method to run an [aggregation pipeline.](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline) [source]
This example groups all documents by the date of the measurement, then calculates the average of all temperature measurements that day and returns a [cursor:](https://www.mongodb.com/docs/manual/core/cursors.md#std-label-cursors) [source]
For additional query functionality, you can use the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) method to run an [aggregation pipeline.](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline) [source]
After MongoDB builds your index, return to your notebook and run vector search queries on your data. The following examples demonstrate different queries that you can run on your vectorized data. [source]
Increasing the value of `maxNumActiveUserIndexBuilds` allows additional concurrent index builds at the cost of increased pressure on the WiredTiger cache. [source]
[`storageSize`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.storageSize) does not include index size. See [`totalIndexSize`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.totalIndexSize) for index sizing. [source]
Defines the maximum size of the internal cache that WiredTiger uses for all data. The memory consumed by an index build (see [`maxIndexBuildMemoryUsageMegabytes`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.maxIndexBuildMemoryUsageMegabytes)) is separate from the WiredTiger cache memory. [source]
Defines the maximum amount of memory to allocate for cache as a percentage of physical RAM. The memory that an index build consumes (see [`maxIndexBuildMemoryUsageMegabytes`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.maxIndexBuildMemoryUsageMegabytes)) is separate from the WiredTiger cache memory. [source]
Enables or disables [prefix compression](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-prefix-compression) for index data. [source]
Specify `true` for [`--wiredTigerIndexPrefixCompression`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--wiredTigerIndexPrefixCompression) to enable [prefix compression](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-prefix-compression) for index data, or `false` to disable prefix compression for index data. [source]
The [`--wiredTigerIndexPrefixCompression`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--wiredTigerIndexPrefixCompression) setting affects all indexes created. If you change the value of [`--wiredTigerIndexPrefixCompression`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--wiredTigerIndexPrefixCompression) on an existing MongoDB deployment, all new indexes use prefix compression. Existing indexes are not affected. [source]
WiredTiger uses [prefix compression](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-prefix-compression) on all indexes by default. [source]
You must specify the `key` field for `$geoNear` on a time series collection. [source]
Starting in MongoDB 7.0, you can use the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) aggregation stage to write documents to a time series collection. For more information, see [Migrate Data into a Time Series Collection.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-migrate-data-into-timeseries-collection.md#std-label-migrate-data-into-a-timeseries-collection) [source]
- Fill gaps in time series data. [source]
The following command runs `$collStats` with the `storageStats: {}` option on a `weather` time series collection using the [WiredTiger Storage Engine](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger), and filters for only time series data: [source]
- Data is high volume, since each individual time series requires a large, constantly growing number of documents. [source]
- Reduced complexity for working with time series data [source]
Configure, create, and query a time series collection with MongoDB Atlas or a self-managed deployment. [source]
As you work with time series code examples, add them between the `// start example code here` and `// end example code here` comments. [source]
This exercise uses [stock ticker sample data](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-quick-start.md#std-label-ts-quick-start-sample-data). The `date` field stores time data, and the `ticker` field identifies the individual stock. [source]
This creates a reference to an empty "timeseries" database. [source]
6. Create an empty time series collection. [source]
This creates an empty time series collection named `stocks`. [source]
You query a time series collection like any other MongoDB collection. For more information, see [About Querying Time Series Data.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-querying.md#std-label-timeseries-querying) [source]
7) Create an empty time series collection. [source]
6) Create an empty time series collection. [source]
7. Create an empty time series collection. [source]
This creates and switches to an empty "timeseries" database. [source]
5. Create an empty time series collection. [source]
```javascript const timeSeriesDB = client.db('timeseries'); [source]
5) Create an empty time series collection. [source]
As you work with time series code examples, add them between the `# start example code here` and `# end example code here` comments. [source]
```python timeseries_db = client["timeseries"] [source]
```python timeseries_db.create_collection("stocks", timeseries=time_series_options) [source]
- To migrate existing data into a time series collection, see [Migrate Data into a Time Series Collection.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-migrate-data-into-timeseries-collection.md#std-label-migrate-data-into-a-timeseries-collection) [source]
- To learn how MongoDB stores time series data internally, see [About Time Series Data.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-bucketing.md#std-label-timeseries-bucketing) [source]
2. Create your time series collection. [source]
Before you can output data to a time series collection, you must create the collection with the appropriate options. In this example, we create a `TimeSeriesOptions` object to define the time series options for the new collection, and then create the collection using those options: [source]
Then, add an [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) aggregation stage to your pipeline that outputs to the new time series collection. Create the output, and then concatenate it to your existing aggregation pipeline: [source]
For a full explanation of the time series options, see the [Time Series Field Reference.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-procedures.md#std-label-time-series-fields) [source]
After you run this aggregation pipeline, you can use the standard MongoDB query methods to review the data in your new time series collection. The following example shows how to use the `Find` and `ToList` methods to view a document in your `weather_new` time series collection: [source]
2) Create your time series collection. [source]
- Uses [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) with the `timeseries` option to create a `weather_new` time series collection in the `mydatabase` database. [source]
For the aggregation stage syntax, see [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out). For a full explanation of the time series options, see the [Time Series Field Reference.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-procedures.md#std-label-time-series-fields) [source]
After you run this aggregation pipeline, you can use `find().first()` method to view a document in your `weather_new` time series collection: [source]
After you run this aggregation pipeline, you can use [`findOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findone.md#mongodb-method-db.collection.findOne) to view a document in your `weather_new` time series collection: [source]
After you run this aggregation pipeline, you can use `findOne()` method to view a document in your `weather_new` time series collection: [source]
After you run this aggregation pipeline, you can use `find_one()` method to view a document in your `weather_new` time series collection: [source]
- Starting in MongoDB 7.0.3 and 7.1, `$out` can take a document to output to a [time series collection:](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-landing) [source]
If specified collection exists and the `$out` operation specifies `timeseries` options, then the following restrictions apply: [source]
1. The existing collection must be a time series collection. [source]
3. The `timeseries` options included in the `$out` stage must exactly match those on the existing collection. [source]
1. Create a new time series collection. [source]
```javascript mongodump --uri="mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/weather" \ --collection=temporarytimeseries --out=timeseries ``` [source]
```javascript 2021-06-01T16:48:39.980+0200 writing weather.temporarytimeseries to timeseries/weather/temporarytimeseries.bson 2021-06-01T16:48:40.056+0200 done dumping weather.temporarytimeseries (10000 documents) ``` [source]
The following operation imports `timeseries/weather/temporarytimeseries.bson` into the new collection `weathernew`: [source]
```javascript mongorestore --uri="mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/weather" \ --collection=weathernew --noIndexRestore \ --maintainInsertionOrder \ timeseries/weather/temporarytimeseries.bson ``` [source]
- Analysis of complex time series information without exporting the data to an external database. [source]
For an additional example about IOT (Internet of Things) Power Consumption, see the [Practical MongoDB Aggregations](https://www.practical-mongodb-aggregations.com/examples/time-series/iot-power-consumption.html) e-book. [source]
By default, MongoDB clusters time series collections based on bucket time. [source]
A document that reports metrics related to the [internal storage of time series collections.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-bucketing.md#std-label-timeseries-bucket-catalog) [source]
You can also use the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#mongodb-pipeline-pipe.-collStats) aggregation pipeline stage to find time series metrics. To learn more, see [storageStats Output on Time Series Collections.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#std-label-storage-stats-time-series) [source]
The total number of time series collections. [source]
Once all documents in a bucket are expired, the background task that removes expired buckets removes the bucket during the next run. See [Timing of Delete Operations](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-automatic-removal.md#std-label-timeseries-collection-delete-operations-timing) for more information. [source]
The document would expire from the database at `"2021-05-19T10:00:00.000Z"`. Once all documents in a bucket are expired, the background task that removes expired buckets removes the bucket during the next run. See [Timing of Delete Operations](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-automatic-removal.md#std-label-timeseries-collection-delete-operations-timing) for more information. [source]
For efficient time series data storage, MongoDB provides time series collections. [source]
You can [create time series collections in the UI](https://www.mongodb.com/docs/atlas/atlas-ui/collections.md#std-label-atlas-ui-create-a-collection) for deployments hosted in [MongoDB Atlas.](https://www.mongodb.com/docs/atlas) [source]
Time series collections generally behave like other MongoDB collections. [source]
You can only create time series collections on a system with [featureCompatibilityVersion](https://www.mongodb.com/docs/manual/reference/command/setfeaturecompatibilityversion.md#std-label-view-fcv) set to 5.0 or greater. [source]
The steps below outline how to effectively configure a time series collection's settings. [source]
You query a time series collection the same way you query a standard MongoDB collection. [source]
The query was issued on a timeseries collection. [source]
$queryStats does not collect query shape statistics for update operations on time series collections. [source]
$queryStats does not collect query shape statistics for insert operations on time series collections. [source]
$queryStats does not collect query shape statistics for delete operations on time series collections. [source]
If your collection stores data that you want to compare across time intervals, use a time series collection to improve performance and storage. For more information on the benefits of time series collections, see [Time Series Collections.](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection) [source]
You can create time series collections in the UI for deployments hosted in MongoDB Atlas. [source]
`$queryStats` does not collect query shape statistics for `update` operations on [time series collections.](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection) [source]
`$queryStats` does not collect query shape statistics for `insert` operations on [time series collections.](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection) [source]
`$queryStats` does not collect query shape statistics for `delete` operations on [time series collections.](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection) [source]
| Number | Description | | --- | --- | | 0 | Generic binary subtype | | 1 | Function data | | 2 | Binary (old) | | 3 | UUID (old) | | 4 | UUID | | 5 | MD5 | | 6 | Encrypted BSON value | | 7 | Compressed time series data **New in version 5.2** | | 8 | Sensitive data, such as a key or secret. MongoDB does not log literal values for binary data with subtype 8. Instead, MongoDB logs a placeholder value of `###`. | | 9 | Vector data, which is densely packed arrays of numbers of the same type. | | 128 | Custom data | [source]
Comparing Time Series Collections to Regular Collections [source]
You can output a list of collections in a database and filter the results by a variety of properties, including collection type. You can use this functionality to list all time series collections in a database. [source]
- `options: { timeseries: { ... } }` [source]
You can use [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) to move data from a time series collection to another collection. [source]
Starting in MongoDB 8.0.10, you can reshard a time series collection. All shards in the time series collection must run version 8.0.10 or later to reshard. [source]
MongoDB supports reads from time series collections in transactions. [source]
If an embedded data model supports your application's needs, use nested fields. The behavior of nested fields does not differ between regular collections and time series collections. [source]
General indexing strategies also apply to time series collections. For more information, see Indexing Strategies. [source]
- Queryable Encryption does not support [Views](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page), [Time Series Collections](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), or [capped collection.](https://www.mongodb.com/docs/manual/core/capped-collections.md#std-label-manual-capped-collection) [source]
The `expireAfterSeconds` option is only available for [time series collections](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-landing) and [clustered collections.](https://www.mongodb.com/docs/manual/core/clustered-collections.md#std-label-clustered-collections) [source]
- Shards an existing time series collection named `deliverySensor` on the `test` database. [source]
- [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc): Returns a date that has been truncated to the specific unit. [source]
- Uses [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) to truncate each document's `date` to the appropriate month. [source]
Together, [binSize](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-binSize) and [unit](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-unit) specify the time period used in the [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) calculation. [source]
- Divides the time for the [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) calculation into [binSize](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-binSize) time periods in the specified time [unit.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-unit) [source]
- A string other than `week`, [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) uses a reference date of `2000-01-01T00:00:00.00Z`. For example, if [binSize](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-binSize) is `10` and [unit](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-unit) is `year`, example time periods are: [source]
- Equal to `week`, [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) uses a reference date that is set to the earliest first day of the week that is greater than or equal to `2000-01-01`. The first day is set using [startOfWeek](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-startOfWeek) (the default is Sunday). [source]
- `year`: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) returns the [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) for the start of January 1 for the year in [date.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-date) [source]
- `quarter`: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) returns the [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) for the start of the first day of the calendar quarter in [date.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-date) [source]
- `month`: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) returns the [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) for the start of the first day of the month in [date.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-date) [source]
- `day`: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) returns the [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) for the start of the day in [date.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-date) [source]
- `hour`: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) returns the [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) for the start of the hour in [date.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-date) [source]
- `minute`: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) returns the [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) for the start of the minute in [date.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-date) [source]
- `second`: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) returns the [ISODate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ISODate) for start of the second in [date.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-date) [source]
- Specified: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) uses [startOfWeek](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-startOfWeek) as the first day of the week for the calculation. [source]
- Omitted: [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) uses Sunday as the start of the week for the calculation. [source]
This example uses [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) in a [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage to truncate the cake sales `orderDate` values to two weeks: [source]
This example uses [`$dateTrunc`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#mongodb-expression-exp.-dateTrunc) in a [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) stage to truncate the cake sales `orderDate` values to six months and return the sum of the `quantity` values: [source]
- `$dateTrunc` truncates the `orderDate` field to a `6` [binSize](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-binSize) `month` [unit](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetrunc.md#std-label-dateTrunc-unit) time period. [source]
The last point is always implicitly connected to the first. You can specify as many points, i.e. sides, as you like. [source]

Related concepts

index — is a related of MongoDB time-series query execution: bucket unpacking, pushdown, block processing and sorts
time series query — is a part of MongoDB time-series query execution: bucket unpacking, pushdown, block processing and sorts
working set for time series — is a measure of MongoDB time-series query execution: bucket unpacking, pushdown, block processing and sorts
block processing — is a part of MongoDB time-series query execution: bucket unpacking, pushdown, block processing and sorts
time series sharding — is a related of MongoDB time-series query execution: bucket unpacking, pushdown, block processing and sorts

Children

No children recorded.

← the whole tree · 3D view· how to read this page