Statistics method placement clarification #2224
Conversation
There was a problem hiding this comment.
Pull request overview
This PR clarifies the proper placement and behavior of the .Statistics method in RavenDB query documentation. The update addresses potential confusion about when and where to call .Statistics to ensure query statistics are properly captured.
Changes:
- Added important usage guidance for the
.Statisticsmethod across multiple documentation versions - Clarified that
.Statisticsmust be called on the final query object before execution/materialization - Warned about statistics not being carried over when converting between query types
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx | Added Statistics method placement clarification to the current documentation |
| versioned_docs/version-7.1/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx | Applied same clarification to version 7.1 documentation |
| versioned_docs/version-7.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx | Applied same clarification to version 7.0 documentation |
| versioned_docs/version-6.2/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx | Applied same clarification to version 6.2 documentation |
| versioned_docs/version-6.0/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx | Applied same clarification to version 6.0 documentation with additional blank line |
| versioned_docs/version-5.4/client-api/session/querying/_how-to-get-query-statistics-csharp.mdx | Applied same clarification to version 5.4 documentation with additional blank line |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| are returned in the `QueryStatistics` object. | ||
|
|
||
| * `Statistics` should be called on the **final query object that is executed/materialized** (e.g. by calling `ToList`, `ToListAsync`, `First`, `FirstOrDefault`, etc.). If you convert between query types (e.g. `ToDocumentQuery()`, `ToAsyncDocumentQuery()`, `ToQueryable()`), a new query object may be created and previously-requested statistics will **not** be carried over. In such cases, the original `stats` variable will remain with its default values. | ||
|
|
There was a problem hiding this comment.
The Statistics method is NOT available on the IRavenQueryable interface when using a Where predicate.
This means that the sample code below (in the Query and Query_async tabs) must be fixed to:
List<Employee> employees = session
.Query<Employee>()
.Where(x => x.FirstName == "Anne")
.ToDocumentQuery() // => must convert to DocumentQuery
.Statistics(out QueryStatistics stats)
.ToList();
We should also include a basic example of a collection query, one that does not use any filters, where Statistics() can be called directly without conversion.
=> This will be handled separately in issue:
https://issues.hibernatingrhinos.com/issue/RDoc-3645/Get-query-statistics-Fix-examples
As discussed w/ @Scooletz
For now, suggesting the following text for this PR:
* Always call `Statistics()` on the **final** query instance that you will execute - the one on which you ultimately call _ToList()_, _ToListAsync()_, _First()_, _FirstOrDefault()_, and so on.
If you call `Statistics()` on one query object and then convert it to a different type (e.g. by calling `ToDocumentQuery()`, `ToQueryable()`), a new query object is created,
and the previously-requested statistics will not be carried over.
In such cases, the original `QueryStatistics` object will remain with its default values.
There was a problem hiding this comment.
Changes reflected in the commit below.
4 participants
https://issues.hibernatingrhinos.com/issue/RDoc-3646/Statistics-docs-should-clarify-the-placement-of-the-method
Clarify the placement of the
.Statisticsmethod