Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / /

$queryStats (aggregation)

Nesta página

  • Definição
  • Requisitos
  • Sintaxe
  • Campos de comando
  • Controle de acesso
  • Comportamento
  • Como $queryStats rastreia estatísticas de query
  • Como os Grupos $queryStats Retornaram documento
  • Como $queryStats transforma dados usando transformIdentifiers
  • $queryStats Log Entries
  • Saída
  • collectionType
  • forma de query
  • Exemplos
  • Exemplo não transformado
  • Exemplo transformado
  • Collection de dados do MongoDB Atlas

Novidades na versão 7.0.12: (Também disponível a partir de 6.0.7)

$queryStats

Aviso

O estágio de agregação $queryStats não é suportado e não é garantido que seja estável em uma versão futura. Não crie uma funcionalidade que dependa de um formato de saída específico desse estágio, pois a saída pode mudar em uma versão futura.

Retorna estatísticas de tempo de execução para query registradas.

$queryStats coleta e reporta métricas para queries do aggregate(), find() e distinct() . O $queryStats não coleta informações para queries que usam Queryable Encryption.

O estágio $queryStats é ativado em sistemas hospedados no MongoDB Atlas com uma camada do cluster de pelo menos M10.

Para executar o estágio $queryStats , seu pipeline deve atender aos seguintes requisitos:

  • O pipeline deve ser executado no banco de dados admin .

  • $queryStats deve ser o primeiro estágio do pipeline.

db.adminCommand( {
aggregate: 1,
pipeline: [
{
$queryStats: {
transformIdentifiers: {
algorithm: <string>,
hmacKey: <binData> /* subtype 8 - used for sensitive data */
}
}
}
],
cursor: { }
} )

Importante

Você não pode executar $queryStats em uma collection específica. Para obter exemplos completos, consulte Exemplos.

$queryStats usa os seguintes campos:

Campo
necessidade
Tipo
Descrição
transformIdentifiers
Opcional
Documento
Especifica opções de transformação adicionais para a saída $queryStats .
transformIdentifiers
.algorithm
Obrigatório ao especificar o objeto transformIdentifiers
String
O tipo de transformação de hash aplicada às informações de namespace e nomes de campo na saída. O único valor algorithm suportado no momento é hmac-sha-256.
transformIdentifiers
.hmacKey
Obrigatório ao especificar o objeto transformIdentifiers
BinData
A entrada de chave privada na transformação HMAC.

Se a sua implementação impuser controle de acesso, o usuário executando o $queryStats deverá ter as seguintes permissões:

  • Para executar o $queryStats sem a opção transformIdentifiers , o usuário deve ter a ação de privilégio queryStatsRead .

  • Para executar o $queryStats com a opção transformIdentifiers , o usuário deve ter as ações de privilégio do queryStatsRead e queryStatsReadTransformed .

O role clusterMonitor integrado fornece os privilégios queryStatsRead e queryStatsReadTransformed . O exemplo a seguir concede a função clusterMonitor no reconhecimento de data center admin :

db.grantRolesToUser(
"<user>",
[ { role: "clusterMonitor", db: "admin" } ]
)

As seções a seguir descrevem detalhes comportamentais do estágio $queryStats .

As estatísticas do estágio $queryStats são rastreadas em uma collection virtual armazenada na memória. O limite de memória para a collection virtual é de 1% da memória total do sistema.

$queryStats agrupa queries com propriedades comuns no mesmo documento de saída. O documento resultante é chamado de entrada de estatísticas de query.

$queryStats agrupa query semelhantes normalizando valores de campo fornecidos pelo usuário para seus tipos de dados. Por exemplo, um filtro especificado como { item: 'card' } é normalizado para { item : '?string'}. $queryStats também normaliza os valores de algumas opções de query, como hint e comment.

$queryStats preserva valores literais para opções como readConcern e readPreference.

Para obter a lista completa de opções incluídas em uma entrada de estatísticas de query, consulte localizar a forma de query do comando.

Quando uma chave HMAC é especificada para a opção transformIdentifiers , o $queryStats utiliza a chave HMAC para aplicar uma função de hash HMAC-SHA-256 nos seguintes dados:

  • Nomes dos campos do documento

  • Nomes de coleção

  • nomes de banco de dados

$queryStats não aplica a transformação HMAC aos seguintes dados:

  • Palavras-chave MQL, como nomes de operadores (por exemplo, $gte ).

  • Nomes de parâmetros como o parâmetro partitionBy em $setWindowFields.

  • Valores do campo. $queryStats normaliza os valores de campo em uma query para seus tipos de dados (como número ou string) quando a query é registrada. $queryStats nunca armazena valores de campo que contêm dados do usuário.

Para obter um exemplo de saída transformada, consulte Exemplo transformado.

O MongoDB registra $queryStats operações nos registros de sistema. Por padrão, o MongoDB registra apenas a invocação de operações $queryStats , não a saída da operação. Para operações do $queryStats que incluem a opção transformIdentifiers , você pode especificar se a saída transformada está incluída na entrada de registro.

Para saber como controlar o comportamento de registro do $queryStats , consulte Alternar saída de registro do $queryStats.

$queryStats retorna uma matriz de entradas de estatísticas de consulta. Algumas propriedades de entrada de estatísticas de query contêm valores literais e algumas propriedades são normalizadas para agrupar queries comuns.

As entradas de estatísticas de query contêm os seguintes documentos de nível superior:

Documento
Descrição
key

A combinação exclusiva de atributos que definem uma entrada na saída de estatísticas de query. O key contém atributos como:

  • forma de query

  • Informações do cliente

  • preocupação de leitura

  • collectionType

Cada combinação única de atributos cria uma entrada separada na collection virtual do $queryStats .

asOf
A hora UTC em que $queryStats leu esta entrada da collection virtual $queryStats . asOf não retorna necessariamente o mesmo horário UTC para cada resultado. Internamente, a estrutura de dados é particionada e cada partição será lida em um ponto individual no tempo.
metrics
Contém métricas agregadas de tempo de execução associadas a cada entrada de estatísticas de query. Cada entrada de estatísticas de query registra estatísticas para cada query que compartilha a mesma chave.

Cada documento na array de saída contém os seguintes campos:

Campo
Tipo
Literal ou Normalizado
Descrição
key
Documento
literal
Contém a forma de query e atributos de query adicionais que agrupam um conjunto de queries
key.queryShape
Documento
literal
Contém atributos usados para agrupar queries semelhantes. Para obter mais informações, consulte Forma de query.
key.client
Documento
literal
Descreve as informações do cliente associadas à chave
key.client.application
Documento
literal
O nome do aplicativo cliente
key.client.driver
Documento
literal
Descreve o driver usado para emitir a query
key.client.driver.name
String
literal
Nome do driver usado para emitir a query. Os valores possíveis incluem mongosh e nodejs.
key.client.driver.version
String
literal
Número da versão do driver usado para emitir a query
key.client.os
Documento
literal
Descreve o sistema operacional usado pelo cliente que emitiu a query
key.client.os.type
String
literal
Tipo do sistema operacional
key.client.os.name
String
literal
Nome do sistema operacional
key.client.os.architecture
String
literal
Arquitetura do sistema operacional. Os valores possíveis incluem arm64 e x86_64.
key.client.os.version
String
literal
Número da versão do sistema operacional
key.readConcern
Documento
literal
A referência de leitura para a chave
key.collectionType
String
literal
O tipo de coleção para o qual a query foi emitida. Para obter mais informações, consulte Tipo de coleção.
key.hint
Documento ou string
Normalizado
O índice que foi usado como dica para a query
key.batchSize
String
Normalizado
O tamanho do lote da chave. O tamanho do lote especifica o número de documentos a serem devolvidos em cada lote da resposta da instância MongoDB.
key.comment
String
Normalizado
Comentário associado à chave
key.maxTimeMS
String
Normalizado
valor maxTimeMS associado à chave
key.noCursorTimeout
Boolean
Normalizado
Opção noCursorTimeout associada à chave
key.allowPartialResults
String
literal
Opção allowPartialResults associada à chave
key.readPreference
String
literal
preferência de leitura associada à chave
key.apiVersion
String
literal
A versão da API estável associada à chave. Consulte API estável.
key.apiStrict
Boolean
literal
O valor do parâmetro apiStrict associado à chave. Consulte stable API.
key.apiDeprecationErrors
Boolean
literal
O valor do parâmetro apiDeprecationErrors associado à chave. Consulte stable API.
keyHash
String
literal
Uma representação em hash dos valores no key. Cada valor keyHash único corresponde a uma entrada única no armazenamento de memória $queryStats .
metrics
Documento
literal
Descreve estatísticas de tempo de execução para a chave
metrics.lastExecutionMicros
Número longo
literal
Tempo de execução de execução para a query mais recente para todas as queries com a chave fornecida
metrics.execCount
Número longo
literal
Número de vezes que a query com a chave fornecida foi executada
metrics.keysExamined
Documento
literal
Descreve o número de chaves examinadas por queries
metrics
.keysExamined
.sum
Inteiro
literal
Número total de chaves examinadas
metrics
.keysExamined
.max
Número longo
literal
Número máximo de chaves examinadas
metrics
.keysExamined
.min
Número longo
literal
Menor número de chaves examinadas
metrics
.keysExamined
.sumOfSquares
NumberDecimal
literal

Soma dos quadrados do número de chaves examinadas.

Um valor sumOfSquares alto indica alta variação no número de chaves examinadas em queries individuais.

metrics.docsExamined
Documento
literal
Descreve o número de documentos examinados por queries
metrics
.docsExamined
.sum
Inteiro
literal
Número total de documentos examinados na query
metrics
.docsExamined
.max
Número longo
literal
Número máximo de documentos examinados
metrics
.docsExamined
.min
Número longo
literal
Número mínimo de documentos examinados
metrics
.docsExamined
.sumOfSquares
NumberDecimal
literal

Soma de quadrados do número de documentos examinados.

Um valor sumOfSquares alto indica alta variação no número de documentos examinados em queries individuais.

metrics.hasSortStage
Boolean
literal
true quando o MongoDB deve classificar os documentos depois de recebê-los de um cursor.
metrics.usedDisk
Boolean
literal
true quando a query grava dados em arquivos temporários devido a restrições de memória.
metrics.fromMultiPlanner
Boolean
literal
true quando o planejador de query avalia vários planos antes de escolher o plano de execução vencedor para a query.
metrics.fromPlanCache
Boolean
literal
true quando o planejador de query é capaz de usar um plano a partir do cache do plano.
metrics.totalExecMicros
Documento
literal

Descreve o tempo total gasto executando query com a chave fornecida. Se a query resultou em getMores, totalExecMicros inclui o tempo gasto processando as getMore solicitações. totalExecMicros não inclui o tempo gasto aguardando o cliente.

Todos os subcampos de totalExecMicros são relatados em microssegundos.

metrics
.totalExecMicros
.sum
Número longo
literal
Tempo total gasto executando query com a chave fornecida
metrics
.totalExecMicros
.max
Número longo
literal
Maior tempo gasto executando uma query com a chave fornecida
metrics
.totalExecMicros
.min
Número longo
literal
Menor tempo gasto executando uma query com a chave fornecida
metrics
.totalExecMicros
.sumOfSquares
NumberDecimal
literal
Soma dos quadrados do tempo total de execução de todas as query com a chave fornecida. Um valor alto de sumOfSquares indica alta variação nos tempos de execução da query.
metrics
.firstResponseExecMicros
Documento
literal

Descreve o tempo gasto desde quando uma query dentro da chave começou a ser processada até quando o servidor retorna o primeiro lote de resultados

Todos os subcampos de firstResponseExecMicros são relatados em microssegundos.

metrics
.firstResponseExecMicros
.sum
Número longo
literal
Quantidade combinada de tempo gasto desde o início do processamento da query até quando o servidor retorna o primeiro lote de resultados
metrics
.firstResponseExecMicros
.max
Número longo
literal
Maior tempo gasto desde o início do processamento de query até quando o servidor retorna o primeiro batch de resultados
metrics
.firstResponseExecMicros
.min
Número longo
literal
O menor tempo gasto desde o início do processamento da query até quando o servidor retorna o primeiro lote de resultados
metrics
.firstResponseExecMicros
.sumOfSquares
NumberDecimal
literal

Soma dos quadrados do tempo gasto desde o início do processamento da query até quando o servidor retorna o primeiro lote de resultados.

Um valor alto de sumOfSquares indica alta variação nos tempos de processamento da query.

metrics.docsReturned
Documento
literal
Descreve o número de documento retornados por query dentro da chave
metrics
.docsReturned
.sum
Número longo
literal
Número total de documento retornados por query com a chave fornecida
metrics
.docsReturned
.max
Número longo
literal
Número máximo de documentos retornados por uma query com a chave fornecida
metrics
.docsReturned
.min
Número longo
literal
Menor número de documentos retornados por uma query com a chave fornecida
metrics
.docsReturned
.sumOfSquares
NumberDecimal
literal

Soma dos quadrados do número de documentos retornados por uma query dentro da chave.

Um valor alto de sumOfSquares indica alta variação no número de documento retornados entre query individuais.

metrics.firstSeenTimestamp
Data
literal
Tempo em que uma query com a chave fornecida foi usada pela primeira vez desde a última reinicialização
metrics.lastSeenTimestamp
Data
literal
Hora em que uma query com a chave fornecida foi usada mais recentemente

O campo key.collectionType indica o tipo de collection em que a query registrada foi emitida. O collectionType pode ser um dos seguintes valores:

Campo
Descrição
changeStream
collection
A query foi emitida em uma collection padrão.
nonExistent
A query foi emitida em uma collection que não existe.
timeseries
A query foi emitida em uma coleção de séries temporais.
view
A query foi emitida em uma visualização.
virtual

A query foi emitida em uma collection virtual. As seguintes operações ocorrem em collections virtuais:

O key.queryShape contém atributos de query utilizados para agrupar queries semelhantes. Os campos em key.queryShape variam de acordo com o comando que resultou na entrada das estatísticas da consulta. $queryStats cria entradas de estatísticas de query para comandos aggregate, find e distinct .

Cada propriedade de forma de query corresponde a uma opção de query. Por exemplo, key.queryShape.sort corresponde à especificação sort() para a forma de query.

A tabela a seguir descreve as propriedades da forma de query para comandos find .

Campo
Tipo
Literal ou Normalizado
key.queryShape.filter
Documento
Normalizado
key.queryShape.sort
Documento
literal
key.queryShape.projection
Documento
Normalizado
key.queryShape.skip
Inteiro
Normalizado
key.queryShape.limit
Inteiro
Normalizado
key.queryShape.singleBatch
Boolean
literal
key.queryShape.max
Documento
Normalizado
key.queryShape.min
Documento
Normalizado
key.queryShape.returnKey
Boolean
literal
key.queryShape.showRecordId
Boolean
literal
key.queryShape.tailable
Boolean
literal
key.queryShape.oplogReplay
Boolean
literal
key.queryShape.awaitData
Boolean
literal
key.queryShape.collation
Documento
literal
key.queryShape.allowDiskUse
Boolean
literal
key.queryShape.let
Documento
Normalizado

A tabela a seguir descreve as propriedades da forma de query para comandos aggregate .

Campo
Tipo
Literal ou Normalizado
key.queryShape.pipeline
Array
Normalizado
key.queryShape.explain
Boolean
literal
key.queryShape.allowDiskUse
Boolean
literal
key.queryShape.collation
Documento
literal
key.queryShape.hint
string ou documento
Normalizado
key.queryShape.let
Documento
Normalizado

A tabela a seguir descreve as propriedades da forma de query para comandos distinct .

Campo
Tipo
Literal ou Normalizado
key.queryShape.key
String
literal
key.queryShape.collation
Documento
Normalizado
key.queryShape.query
Documento
Normalizado

Para executar os exemplos nesta seção, comece com os seguintes dados:

db.products.insertMany(
[
{ item: "card", qty: 15 },
{ item: "envelope", qty: 20 },
{ item: "stamps" , qty: 30 }
]
)

Em seguida, execute estes comandos:

db.products.find( { item: "card" } )
db.products.aggregate( [
{
$match: { qty: { $gt: 20 } }
}
] )

Os seguintes exemplos mostram a saída do $queryStats utilizando diferentes tipos de transformação de dados:

Entrada:

db.getSiblingDB("admin").aggregate( [
{
$queryStats: { }
}
] )

Saída:

[
{
key: {
queryShape: {
cmdNs: { db: 'test', coll: 'products' },
command: 'find',
filter: { item: { '$eq': '?string' } }
},
client: {
driver: { name: 'nodejs|mongosh', version: '5.1.0' },
os: {
type: 'Darwin',
name: 'darwin',
architecture: 'arm64',
version: '22.6.0'
},
platform: 'Node.js v16.19.1, LE (unified)',
version: '5.1.0|1.8.0',
application: { name: 'mongosh 1.8.0' }
},
collectionType: 'collection'
},
keyHash: 'dsoJ+LHAru0z6MJ1/IygJnnLTrlpVYYmPnlmNZbZrLI=',
metrics: {
lastExecutionMicros: Long("4254"),
execCount: Long("1"),
totalExecMicros: {
sum: Long("4254"),
max: Long("4254"),
min: Long("4254"),
sumOfSquares: Decimal128("18096516")
},
firstResponseExecMicros: {
sum: Long("4254"),
max: Long("4254"),
min: Long("4254"),
sumOfSquares: Decimal128("18096516")
},
docsReturned: {
sum: Long("1"),
max: Long("1"),
min: Long("1"),
sumOfSquares: Decimal128("1")
},
firstSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z"),
latestSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z")
},
asOf: Timestamp({ t: 1694695007, i: 0 })
},
{
key: {
queryShape: {
cmdNs: { db: 'test', coll: 'products' },
command: 'aggregate',
pipeline: [
{ '$match': { qty: { '$gt': '?number' } } }
]
},
apiVersion: '1',
client: {
driver: { name: 'nodejs|mongosh', version: '5.1.0' },
os: {
type: 'Darwin',
name: 'darwin',
architecture: 'arm64',
version: '22.6.0'
},
platform: 'Node.js v16.19.1, LE (unified)',
version: '5.1.0|1.8.0',
application: { name: 'mongosh 1.8.0' }
},
collectionType: 'collection',
cursor: { batchSize: '?number' }
},
keyHash: '2QLBfL0m1lliStdN4XvBjqVBtZQ6ffaB2L1pJ99twT8=',
metrics: {
lastExecutionMicros: Long("350"),
execCount: Long("3"),
totalExecMicros: {
sum: Long("3084"),
max: Long("2499"),
min: Long("235"),
sumOfSquares: Decimal128("6422726")
},
firstResponseExecMicros: {
sum: Long("3084"),
max: Long("2499"),
min: Long("235"),
sumOfSquares: Decimal128("6422726")
},
docsReturned: {
sum: Long("3"),
max: Long("1"),
min: Long("1"),
sumOfSquares: Decimal128("3")
},
firstSeenTimestamp: ISODate("2023-11-29T21:16:17.796Z"),
latestSeenTimestamp: ISODate("2023-11-29T21:17:12.385Z")
},
asOf: Timestamp({ t: 1701292827, i: 0 })
}
]

Entrada:

db.getSiblingDB("admin").aggregate( [
{
$queryStats: {
transformIdentifiers: {
algorithm: "hmac-sha-256" ,
hmacKey: BinData(8, "87c4082f169d3fef0eef34dc8e23458cbb457c3sf3n2")
}
}
}
] )

Saída:

[
{
key: {
queryShape: {
cmdNs: {
db: 'Mtrt3iG7dsX5c5uCSIhSVlcu5qD3u3xx2EQnS1dJLxM=',
coll: '3oJE6AyOuf8h5NqWiXETxulFlPm3QUXbMnMjL2EqAU4='
},
command: 'find',
filter: {
'VWVRow7Ure92ajRPfrpWiU8OtDeWcLePFIq0+tooBng=': { '$eq': '?string' }
}
},
client: {
driver: { name: 'nodejs|mongosh', version: '5.1.0' },
os: {
type: 'Darwin',
name: 'darwin',
architecture: 'arm64',
version: '22.6.0'
},
platform: 'Node.js v16.19.1, LE (unified)',
version: '5.1.0|1.8.0',
application: { name: 'mongosh 1.8.0' }
},
collectionType: 'collection'
},
keyHash: 'q4vxam+wbk8tTrl8D0MDFH1LQAbI8fWspfkGKhEUROk=',
metrics: {
lastExecutionMicros: Long("4254"),
execCount: Long("1"),
keysExamined: {
sum: Int("5"),
max: Long("5"),
min: Long("5"),
sumOfSquares: Decimal128("25")
},
docsExamined: {
sum: Long("1"),
max: Long("1"),
min: Long("1"),
sumOfSquares: Decimal128("1")
},
hasSortStage: false,
usedDisk: false,
fromMultiPlanner: false,
fromPlanCache: true,
totalExecMicros: {
sum: Long("4254"),
max: Long("4254"),
min: Long("4254"),
sumOfSquares: Decimal128("18096516")
},
firstResponseExecMicros: {
sum: Long("4254"),
max: Long("4254"),
min: Long("4254"),
sumOfSquares: Decimal128("18096516")
},
docsReturned: {
sum: Long("1"),
max: Long("1"),
min: Long("1"),
sumOfSquares: Decimal128("1")
},
firstSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z"),
latestSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z")
},
asOf: Timestamp({ t: 1694695712, i: 0 })
},
{
key: {
queryShape: {
cmdNs: {
db: 'Mtrt3iG7dsX5c5uCSIhSVlcu5qD3u3xx2EQnS1dJLxM=',
coll: '3oJE6AyOuf8h5NqWiXETxulFlPm3QUXbMnMjL2EqAU4='
},
command: 'aggregate',
pipeline: [
{
'$match': {
'RVqrwNEPotzdKnma/T7s4YcgNvpqO29BMDoni2N4IMI=': { '$gt': '?number' }
}
}
]
},
apiVersion: '1',
client: {
driver: { name: 'nodejs|mongosh', version: '5.1.0' },
os: {
type: 'Darwin',
name: 'darwin',
architecture: 'arm64',
version: '22.6.0'
},
platform: 'Node.js v16.19.1, LE (unified)',
version: '5.1.0|1.8.0',
application: { name: 'mongosh 1.8.0' }
},
collectionType: 'collection',
cursor: { batchSize: '?number' }
},
keyHash: 'HEhpQTYB+/wVoHLkOkMd+EC2jguQlMJ1N/vTE7+b8Js=',
metrics: {
lastExecutionMicros: Long("350"),
execCount: Long("3"),
keysExamined: {
sum: Int("5"),
max: Long("5"),
min: Long("5"),
sumOfSquares: Decimal128("25")
},
docsExamined: {
sum: Long("1"),
max: Long("1"),
min: Long("1"),
sumOfSquares: Decimal128("1")
},
hasSortStage: false,
usedDisk: false,
fromMultiPlanner: false,
fromPlanCache: true,
totalExecMicros: {
sum: Long("3084"),
max: Long("2499"),
min: Long("235"),
sumOfSquares: Decimal128("6422726")
},
firstResponseExecMicros: {
sum: Long("3084"),
max: Long("2499"),
min: Long("235"),
sumOfSquares: Decimal128("6422726")
},
docsReturned: {
sum: Long("3"),
max: Long("1"),
min: Long("1"),
sumOfSquares: Decimal128("3")
},
firstSeenTimestamp: ISODate("2023-11-29T21:16:17.796Z"),
latestSeenTimestamp: ISODate("2023-11-29T21:17:12.385Z")
},
asOf: Timestamp({ t: 1701293302, i: 0 })
},
]

O MongoDB Atlas usa periodicamente $queryStats para coletar dados anônimos sobre suas query, o que ajuda a melhorar os produtos MongoDB. Seus dados também podem ser usados para fazer sugestões de funcionalidades com base no uso. O MongoDB mantém os dados coletados com $queryStats por quatro anos.

Quando o Atlas executa o $queryStats em seu sistema, ele usa uma chave HMAC exclusiva por organização do Atlas para transformar seus dados e evitar a coleta de informações confidenciais.

Voltar

$project