Query Shapes

On this page

Examples

Behavior
Get Started
Learn More

Changed in version 8.0.

A query shape is a set of specifications that group similar queries together. Specifications can include filters, sorts, projections, aggregation pipeline stages, a namespace, and others. Queries that have similar specifications have the same query shape.

Note

Starting in MongoDB 8.0, the pre-existing query shape is renamed to the plan cache query shape, and the queryHash field is renamed planCacheShapeHash. For the components of a command that differentiate plan cache query shapes, see the plan cache query shape definition. MongoDB 8.0 uses the new query shape and the existing plan cache query shape as shown on this page.

In MongoDB 8.0 and earlier versions, the existing plan cache query shape supports:

query planning in plan cache scenarios.
deprecated index filters. (Starting in MongoDB 8.0, use the new query settings for the new query shape.)
a subset of the Aggregation Pipeline.

Starting in MongoDB 8.0, the new query shape supports:

query settings, which you can add with setQuerySettings. (As you'll see later on this page, query settings specify indexes and execution settings for a query shape.)
$queryStats query shape statistics.
the fields and operations also supported by the plan cache query shape. Examples: filter, sort, and projection.
the majority of the fields and operands available for the find, distinct, and aggregate commands. To view the fields and operands for the commands, see the Syntax sections on each command page.
the overall structure of the find, aggregation, and distinct commands, which support a wider range of query shapes than the existing plan cache query shape.
operation rejection filters to block find, aggregation, and distinct commands that have a specified query shape.
the entire aggregation pipeline.

Starting in MongoDB 8.0, you can use a $querySettings pipeline stage to return query settings specified for each query shape.

Examples

The following sections show examples with query shapes for the following example pizzaOrders collection:

db.pizzaOrders.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 19,
     totalNumber: 10, orderDate: ISODate( "2023-03-13T08:14:30Z" ) },
   { _id: 1, type: "pepperoni", size: "medium", price: 20,
     totalNumber: 20, orderDate: ISODate( "2023-03-13T09:13:24Z" ) },
   { _id: 2, type: "pepperoni", size: "large", price: 21,
     totalNumber: 30, orderDate: ISODate( "2023-03-17T09:22:12Z" ) },
   { _id: 3, type: "cheese", size: "small", price: 12,
     totalNumber: 15, orderDate: ISODate( "2023-03-13T11:21:39.736Z" ) }
] )

Matching Query Shapes

The following example query shape shows specifications for a find command on the pizzaOrders collection in the default test database:

find: "pizzaOrders",
filter: {
   orderDate: { $gt: ISODate( "2023-01-20T00:00:00Z" ) }
},
sort: {
   totalNumber: 1
},
$db: "test"

The example filter limits the documents to those with an order date greater than the specified date. The example has an ascending sort on the total number of pizzas ordered.

To view the MongoDB 8.0 queryShapeHash and planCacheShapeHash hexadecimal strings, you can use the explain command.

The following explain examples contain queries with the same query shape:

db.pizzaOrders.explain().find(
   { orderDate: { $gt: ISODate( "2024-05-10T05:15:35Z" ) } } ).
   sort( { totalNumber: 1 }
)
db.pizzaOrders.explain().find(
   { orderDate: { $gt: ISODate( "2024-02-05T07:07:16Z" ) } } ).
   sort( { totalNumber: 1 }
)
db.pizzaOrders.explain().find(
   { orderDate: { $gt: ISODate( "2023-03-08T08:12:25Z" ) } } ).
   sort( { totalNumber: 1 }
)

Because the query shapes are the same, the explain output has the same queryShapeHash for each of the examples, and the same planCacheShapeHash for each. For example:

queryShapeHash: 'AB8ECADEE8F0EB0F447A30744EB4813AE7E0BFEF523B0870CA10FCBC87F5D8F1'
planCacheShapeHash: '48E51110'

Different Query Shape

A query has a different shape if the query has different specifications. For example, if a query has a different filter, sort, projection, namespace, or aggregation pipeline stages.

In the example in the previous section, the example sorts by the totalNumber field. If you change the query sort from totalNumber to a different field, the query has a different query shape.

For example, sorting by pizza price changes the query shape:

db.pizzaOrders.explain().find(
   { orderDate: { $gt: ISODate( "2023-01-20T00:00:00Z" ) } } ).
   sort( { price: 1 }
)

Because the query shape is different from the shape in the previous section, the explain output has a different queryShapeHash from the previous example, and a different planCacheShapeHash. For example:

queryShapeHash: 'AC1ECADBE8F1EB0F417A30741AB4813BE7E0BFEF523B0870CA11FCBC87F1A8B2'
planCacheShapeHash: '31A52130'

Behavior

Starting in MongoDB 8.0, add query settings for query shapes instead of index filters for collections. Index filters are deprecated starting in MongoDB 8.0. Query settings have more functionality than index filters, and index filters aren't persistent after cluster shutdown.

Query settings allow you to use an index for all executions of a query shape in a cluster. Also, to prevent an operation from causing excessive cluster workload, you can reject all operations associated with a query shape using an operation rejection filter.

The query optimizer uses the query settings as an additional input during query planning. The query settings affect the plan selected to run a query that has a matching query shape.

Get Started

To add query settings for a query shape, use setQuerySettings.
To delete query settings, use removeQuerySettings.
To retrieve query settings, use a $querySettings stage in an aggregation pipeline.
To block a query shape, use an operation rejection filter.

Learn More

Back

Query Plans

Tailable Cursors