readPreference

Modos de preferência de leitura

A tabela a seguir resume os modos de preferência de leitura:

For detailed description of the read preference modes, see Read Preference Modes.

Comportamento

• All read preference modes except primary may return stale data because secondaries replicate operations from the primary in an asynchronous process. [1] Ensure that your application can tolerate stale data if you choose to use a non-primary mode.

• A preferência de leitura não afeta a visibilidade dos dados. Os clientes podem ver os resultados das gravações antes que elas sejam reconhecidas ou propagadas para a maioria dos membros do conjunto de réplicas. Para obter detalhes, consulte Isolamento de leitura, consistência e recência.

• A read preference não afeta a consistência causal. As garantias de consistência causal fornecidas por sessões causalmente consistentes para operações de leitura com read concern "majority" e operações de gravação com write concern "majority" são mantidas em todos os membros da implantação do MongoDB.

Modos de preferência de leitura

primary

All read operations use only the current replica set primary. [1] This is the default read mode. If the primary is unavailable, read operations produce an error or throw an exception.

O modo de read preference primary não é compatível com modos de read preference que utilizam listas de conjunto de tags ou maxStalenessSeconds. Se você especificar listas de conjuntos de tags ou um valor maxStalenessSeconds com primary, o driver produzirá um erro.

As transações que contêm operações de leitura devem usar a preferência de leitura primary. Todas as operações em uma determinada transação devem ser roteadas para o mesmo nó.

primaryPreferred

Na maioria das situações, as operações são lidas do nó primário do conjunto. No entanto, se o primário não estiver disponível, como é o caso em situações de failover, as operações são lidas de nós secundários que satisfazem as read preferences demaxStalenessSeconds e as listas de conjuntos de tags.

When the primaryPreferred read preference includes a maxStalenessSeconds value and there is no primary from which to read, the client estimates how stale each secondary is by comparing the secondary's last write to that of the secondary with the most recent write. The client then directs the read operation to a secondary whose estimated lag is less than or equal to maxStalenessSeconds.

Quando a read preference inclui uma lista de conjuntos de tags (um array de conjuntos de tags) e não há um primary do qual ler, o cliente tenta encontrar membros secundários com tags correspondentes (tentando os conjuntos de tags em ordem até encontrar uma correspondência). Quando são encontrados secundários correspondentes, o cliente seleciona um secundário aleatório do grupo mais próximo de secundários correspondentes. Se nenhum secundário tiver tags correspondentes, a operação de leitura produz um erro.

Quando a read preference inclui um valor maxStalenessSeconds e uma lista de conjuntos de tags, o cliente filtra primeiro por obsolescência e, em seguida, pelas tags especificadas.

As operações de leitura utilizando o modo primaryPreferred podem retornar dados obsoletos. Use a opção maxStalenessSeconds para evitar a leitura de secundários que o cliente estima estarem excessivamente obsoletos.

Em clusters fragmentados que habilitam o limitador de taxa de solicitação de entrada, os nós de fragmento que estão reduzindo carga podem retornar erros rotulados como SystemOverloadedError.

Para clusters que têm overloadAwareServerSelectionEnabled definido como true, quando um primário responde com um erro repetível rotulado com SystemOverloadedError, o roteador pode rotear temporariamente as leituras para secundários qualificados em vez do servidor sobrecarregado. Isso se aplica a qualquer preferência de leitura que possa selecionar vários servidores. Por padrão, overloadAwareServerSelectionEnabled está configurado para false.

secondary

As operações são lidas somente dos membros secundários do conjunto. Se nenhum secundário estiver disponível, essa operação de leitura produz um erro ou exceção.

A maioria dos conjuntos de réplicas tem pelo menos um secundário, mas há situações em que pode não haver um secundário disponível. Por exemplo, um conjunto de réplicas com um primary, um secundário e um arbiter pode não ter nenhum secundário se um membro estiver em estado de recuperação ou indisponível.

Quando a preferência de leitura secondary inclui um valor maxStalenessSeconds, o cliente estima a obsolescência de cada secundário comparando a última gravação do secundário com a do primário. Em seguida, o cliente direcionará a operação de leitura para um secundário cujo atraso estimado seja menor ou igual a maxStalenessSeconds. Se não houver um primário, o cliente usará o secundário com a gravação mais recente para comparar.

Quando a read preference inclui uma lista de conjuntos de tags (um array de conjuntos de tags), o cliente tenta encontrar membros secundários com tags correspondentes (tentando os conjuntos de tags em ordem até encontrar uma correspondência). Quando são encontrados secundários correspondentes, o cliente seleciona um secundário aleatório do grupo mais próximo de secundários correspondentes. Se nenhum secundário tiver tags correspondentes, a operação de leitura produz um erro.

Quando a read preference inclui um valor maxStalenessSeconds e uma lista de conjuntos de tags, o cliente filtra primeiro por obsolescência e, em seguida, pelas tags especificadas.

As operações de leitura utilizando o modo secondary podem retornar dados obsoletos. Use a opção maxStalenessSeconds para evitar a leitura de secundários que o cliente estima estarem excessivamente obsoletos.

secondaryPreferred

Operações normalmente leem dados de nós secundários do conjunto de réplica. Se o conjunto de réplica tiver somente um único nó primário e nenhum outro nó, as operações lerão os dados do nó primário.

When the secondaryPreferred read preference includes a maxStalenessSeconds value, the client estimates how stale each secondary is by comparing the secondary's last write to that of the primary. The client then directs the read operation to a secondary whose estimated lag is less than or equal to maxStalenessSeconds. If there is no primary, the client uses the secondary with the most recent write for the comparison. If there are no secondaries with estimated lag less than or equal to maxStalenessSeconds, the client directs the read operation to the replica set's primary.

Quando a read preference inclui uma lista de conjuntos de tags (um array de conjuntos de tags), o cliente tenta encontrar membros secundários com tags correspondentes (tentando os conjuntos de tags em ordem até encontrar uma correspondência). Quando são encontrados secundários correspondentes, o cliente seleciona um secundário aleatório do grupo mais próximo de secundários correspondentes. Se nenhum secundário tiver tags correspondentes, o cliente ignora as tags e leituras do primary.

Quando a read preference inclui um valor maxStalenessSeconds e uma lista de conjuntos de tags, o cliente filtra primeiro por obsolescência e, em seguida, pelas tags especificadas.

As operações de leitura utilizando o modo secondaryPreferred podem retornar dados obsoletos. Use a opção maxStalenessSeconds para evitar a leitura de secundários que o cliente estima estarem excessivamente obsoletos.

nearest

The driver reads from a member whose network latency falls within the acceptable latency window. Reads in the nearest mode do not consider whether a member is a primary or secondary when routing read operations: primaries and secondaries are treated equivalently.

Defina esse modo para minimizar o efeito da latência de rede nas operações de leitura sem preferência por dados atuais ou obsoletos.

Quando a read preference inclui um valor maxStalenessSeconds, o cliente estima o quanto cada secundário está obsoleto comparando a última gravação do secundário com a do primary, se disponível, ou com o secundário com a gravação mais recente se não houver nenhum primary. Em seguida, o cliente filtra qualquer secundário cuja defasagem estimada seja maior que maxStalenessSeconds e direciona aleatoriamente a leitura para um membro restante (primary ou secundário) cuja latência de rede esteja dentro da janela de latência aceitável.

Se você especificar uma lista de conjuntos de tags, o cliente tentará encontrar um membro do conjunto de réplicas que corresponda às listas de conjuntos de tags especificadas e direcionará as leituras para um membro arbitrário do grupo mais próximo.

Quando a read preference inclui um valor maxStalenessSeconds e uma lista de conjuntos de tags, o cliente filtra primeiro por obsolescência e, em seguida, pelas tags especificadas. Das instâncias mongod restantes, o cliente direciona aleatoriamente a leitura para uma instância que esteja dentro da janela de latência aceitável. A documentação da seleção de membro da read preference descreve o processo em detalhes.

As operações de leitura utilizando o modo nearest podem retornar dados obsoletos. Use a opção maxStalenessSeconds para evitar a leitura de secundários que o cliente estima estarem excessivamente obsoletos.

Configurar read preference

When using a MongoDB driver, you can specify the read preference using the driver's read preference API. See the driver API documentation. You can also set the read preference when connecting to the replica set or sharded cluster. For an example, see connection string.

Para uma determinada preferência de leitura, os drivers MongoDB usam a mesma lógica de seleção de membros.

When using mongosh, see cursor.readPref() and Mongo.setReadPref().

Read preference e transações

As transações que contêm operações de leitura devem usar a preferência de leitura primary. Todas as operações em uma determinada transação devem ser roteadas para o mesmo nó.

Considerações adicionais

Considere os seguintes pontos ao usar os estágios $merge ou $out em um pipeline de agregação:

• A partir do MongoDB 5.0, os pipelines com um estágio $merge poderão ser executados em nós secundários do conjunto de réplicas se todos os nós do cluster tiverem a featureCompatibilityVersion definida como 5.0 ou superior e a preferência de leitura permitir leituras secundárias.

  • $merge e os estágios $out são executados em nós secundários, mas as operações de gravação são enviadas para o nó primário.

  • Not all driver versions support $merge operations sent to the secondary nodes. For details, see the driver documentation.

• nas versões anteriores do MongoDB , os pipelines com estágios $out ou $merge sempre são executados no nó principal, e a preferência de leitura não é considerada.

Para as operações mapReduce, somente as operações "inline" mapReduce que não gravam dados são compatíveis com a read preference. Caso contrário, as operações mapReduce serão executadas no nó primário.