Configurar operações CRUD

Visão geral

Neste guia, você pode aprender a usar o driver Node.js para configurar operações de leitura e escrita.

Configurações de leitura e escrita

Você pode controlar como o driver direciona as operações de leitura definindo uma preferência de leitura. Você também pode controlar como o driver lida com a consistência e a durabilidade dos dados definindo uma preocupação de leitura ou preocupação de gravação. As write concerns especificam o nível de durabilidade necessário para os dados ao realizar operações de leitura, e as write concerns especificam como o driver aguarda a confirmação das operações de escrita em um conjunto de réplicas.

É possível definir as opções de preocupação de gravação, preocupação de leitura e preferência de leitura nos seguintes níveis:

Cliente, que define o padrão para todas as execuções de operações, a menos que seja substituído
transação
Database
collection

A lista anterior também indica a ordem crescente de precedência das configurações de opção. Por exemplo, se você definir um nível de preocupação de leitura para uma transação, ele substituirá um nível de preocupação de leitura definido para o cliente.

Dica

Para saber mais sobre as configurações de leitura e gravação, consulte os seguintes guias no manual do MongoDB Server :

Esta seção mostra como definir suas configurações de leitura e gravação em cada nível.

Configuração do cliente

Este exemplo mostra como definir a preferência de leitura, preocupação de leitura e preocupação de gravação de uma instância MongoClient passando um objeto MongoClientOptions para o construtor. O código define as seguintes configurações:

SECONDARY preferência de leitura: Operações de leitura recuperam dados de nós secundários do conjunto de réplicas
local preocupação de leitura: As operações de leitura retornam os dados mais recentes da instância sem garantir que os dados tenham sido gravados na maioria dos membros do conjunto de réplicas
2 preocupação de gravação: O primário e um membro do conjunto de réplicas secundário devem confirmar a operação de gravação

const clientOptions = {
  readPreference: ReadPreference.SECONDARY,
  readConcern: { level: "local" },
  writeConcern: { w: 2 },
};
const client = new MongoClient("mongodb://localhost:27017", clientOptions);

Alternativamente, você pode especificar as configurações de leitura e escrita no URI de conexão, que é passado como um parâmetro para o construtor MongoClient :

const uri = "mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=2";
const clientWithUri = new MongoClient(uri);

Configuração da transação

Este exemplo mostra como definir a preferência de leitura, preocupação de leitura e preocupação de gravação de uma transação passando um objeto TransactionOptions para o método startTransaction(). O código define as seguintes configurações:

PRIMARY preferência de leitura: Operações de leitura recuperam dados do membro primário do conjunto de réplicas
majority preocupação de leitura: as operações de leitura retornam os dados mais recentes da instância que foram gravados para a maioria dos membros do conjunto de réplicas
1 preocupação de gravação: O principal membro do conjunto de réplicas deve confirmar a operação de gravação

const transactionOptions = {
  readPreference: ReadPreference.PRIMARY,
  readConcern: { level: "majority" },
  writeConcern: { w: 1 },
};
const session = client.startSession();
session.startTransaction(transactionOptions);

Configuração do Banco de Dados

Este exemplo mostra como definir a preferência de leitura, preocupação de leitura e preocupação de gravação de um banco de dados chamado test_database passando um objeto DbOptions para o método db() . O código define as seguintes configurações:

PRIMARY_PREFERRED preferência de leitura: as operações de leitura recuperam dados do membro primário do conjunto de réplicas ou de membros secundários se o primário não estiver disponível
available preocupação de leitura: As operações de leitura retornam os dados mais recentes da instância sem garantir que os dados tenham sido gravados na maioria dos membros do conjunto de réplicas
majority preocupação de gravação: A maioria de todos os membros do conjunto de réplicas deve reconhecer a operação de escrita

const dbOptions = {
  readPreference: ReadPreference.PRIMARY_PREFERRED,
  readConcern: { level: "available" },
  writeConcern: { w: "majority" },
};
const db = client.db("test_database", dbOptions);

Configuração da Coleção

Este exemplo mostra como definir a preferência de leitura, preocupação de leitura e preocupação de gravação de uma collection chamada test_collection passando um objeto CollectionOptions para o método collection() . O código define as seguintes configurações:

SECONDARY_PREFERRED preferência de leitura: as operações de leitura recuperam dados dos membros secundários do conjunto de réplicas ou dos membros primários se nenhum secundário estiver disponível
available preocupação de leitura: As operações de leitura retornam os dados mais recentes da instância sem garantir que os dados tenham sido gravados na maioria dos membros do conjunto de réplicas
0 preocupação de gravação: Não solicita confirmação da operação de escrita

const collOptions = {
  readPreference: ReadPreference.SECONDARY_PREFERRED,
  readConcern: { level: "available" },
  writeConcern: { w: 0 },
};
const collection = db.collection("test_collection", collOptions);

Conjuntos de tags

No MongoDB Server, você pode aplicar marcações de valor-chave a membros do conjunto de réplicas de acordo com qualquer critério de sua escolha. Você pode então usar essas tags para direcionar um ou mais nós para uma operação de leitura.

Por padrão, o driver Node.js ignora as marcações ao escolher um membro para ler. Para instruir o driver Node.js a preferir determinadas tags, passe-as como parâmetro para o construtor de classe de preferência de leitura .

Este exemplo de código define a opção readPreference para um conjunto de tags que instrui test_database a preferir leituras de membros secundários do conjunto de réplicas na seguinte ordem:

Membros do centro de dados de Nova York ({ dc: 'ny' })
Membros do centro de dados de São Francisco ({ dc: 'sf' })
Quaisquer membros secundários ({})

const taggedReadPreference = new ReadPreference(
  ReadPreference.SECONDARY,
  [
    { dc: "ny" },
    { dc: "sf" },
    {}
  ]
);
const dbWithTags = client.db(
  "test_database",
  { readPreference: taggedReadPreference }
);

LocalThreshold

Se vários membros do conjunto de réplicas corresponderem à preferência de leitura e aos conjuntos de tags especificados, o driver Node.js lerá a partir dos membros do conjunto de réplicas mais próximos, escolhidos de acordo com o tempo de ping .

Por padrão, o driver usa somente os membros cujos tempos de ping estão dentro de 15 milissegundos do membro mais próximo para queries. Para distribuir leituras entre nós com latências mais altas, passe a opção localThresholdMS para o construtor MongoClient() .

O exemplo a seguir especifica um limite local de 35 milissegundos:

const clientWithLocalThreshold = new MongoClient("mongodb://localhost:27017", {
  replicaSet: "repl0",
  readPreference: ReadPreference.SECONDARY_PREFERRED,
  localThresholdMS: 35
});

No exemplo anterior, o driver Node.js distribui leituras entre nós correspondentes dentro de 35 milissegundos do tempo de ping do nó mais próximo.

Observação

O driver Node.js ignora o valor de localThresholdMS ao se comunicar com um conjunto de réplicas por meio de uma instância mongos. Nesse caso, use a opção de linha de comando localThreshold.

Agrupamentos

Você pode especificar um agrupamento para modificar o comportamento das operações de leitura e gravação. Um agrupamento é um conjunto de regras específicas do idioma para comparação de cadeias de caracteres, como para letras maiúsculas e minúsculas e acentos.

O MongoDB classifica strings utilizando agrupamento binário por padrão. Esse agrupamento padrão usa o padrão ASCII valores de caracteres para comparar e ordenar strings. Idiomas e locais possuem convenções específicas de ordenação de caracteres que diferem do padrão ASCII, e você pode optar por aplicar um conjunto diferente de regras de agrupamento à sua operação.

Você pode especificar um agrupamento nos seguintes níveis:

Collection: define o agrupamento padrão para operações na collection. Você não pode definir uma coleta para uma coleta existente.
Índice: define o agrupamento para operações que usam o índice.
Operação: define o agrupamento da operação e substitui quaisquer agrupamentos herdados.

Campos de agrupamento

O objeto de agrupamento contém os seguintes campos:

collation: {
  locale: <string>,
  caseLevel: <bool>,
  caseFirst: <string>,
  strength: <int>,
  numericOrdering: <bool>,
  alternate: <string>,
  maxVariable: <string>,
  backwards: <bool>
}

Ao configurar a opção collation, você deve especificar o campo locale. Todos os outros campos são opcionais. Para obter uma lista completa dos locais suportados e dos valores padrão dos campos locale, consulte Idiomas e locais suportados no manual do MongoDB Server.

Exemplos de agrupamento

Para especificar um agrupamento, crie um objeto collation e defina seu campo locale para o agrupamento de idioma que você deseja usar. Em seguida, passe esse objeto como um parâmetro de opções para o método correspondente ao nível de agrupamento de destino.

Esta seção inclui exemplos que definem agrupamentos nos níveis de coleta, índice e operação.

Definir agrupamentos de collections e índices

O exemplo a seguir cria uma nova coleta denominada names e define seu agrupamento padrão para o locale "fr_CA":

const db = client.db("db")
db.createCollection("names", {
  collation: { locale: "fr_CA" },
});

Você pode criar um índice na collection names que especifica um agrupamento diferente, como mostrado no exemplo a seguir:

const coll = db.collection("names");
coll.createIndex(
  { "last_name" : 1 },
  { "collation" : { "locale" : "en_US" } });

Definir um agrupamento de operação

Você pode executar uma operação na collection names, criada na seção anterior, que substitui o agrupamento padrão.

A coleção names contém os seguintes documentos:

{ "_id" : 1, "first_name" : "Hans", "last_name" : "Muller" }
{ "_id" : 2, "first_name" : "Gunter", "last_name" : "Braun" }
{ "_id" : 3, "first_name" : "Günter", "last_name" : "Krause" }
{ "_id" : 4, "first_name" : "Jürgen", "last_name" : "Weber" }

Este exemplo chama o método findOneAndUpdate() para atualizar o primeiro documento correspondente que tenha um valor first_name de "Gunter". O código aplica um agrupamento com a locale "de" e a variante de locale "phonebook":

coll.findOneAndUpdate(
  { first_name: { $lt: "Gunter" } },
  { $set: { verified: true } },
  { collation: { locale: "de@collation=phonebook" } },
);

No exemplo anterior, a variante de locale phonebook instrui o driver a classificar os caracteres com umlauts antes dos mesmos caracteres sem umlauts. Como resultado, a operação corresponde ao documento que tem um valor first_name de "Günter", com um trema e retorna as seguintes informações de atualização:

{ lastErrorObject: { updatedExisting: true, n: 1 },
  value: { _id: 3, first_name: 'Günter', last_name: 'Krause' },
  ok: 1 }

Dica

Para saber mais sobre variantes de locale, consulte Variantes locais no manual do MongoDB Server.

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Core API

Gerar valores de _id personalizados