Operações CRUD

Notação de par de valores-chave

Os pares de valores-chave aparecem em muitos contextos diferentes no driver Ruby do MongoDB, e há algumas particularidades de sintaxe relacionadas a como eles podem ser notados que dependem da versão do Ruby que você está usando.

Ao construir um documento, a seguinte sintaxe é aceitável e correta para Ruby versão 1.9 e posterior:

document = { name: "Harriet", age: 36 }

Se você estiver usando o Ruby versão 2.2 ou superior, poderá opcionalmente colocar suas chaves entre aspas.

document = { "name": "Harriet", "age": 36 }

Se você precisar usar qualquer operador do MongoDB que comece com $, como $set, $gte ou $near, deverá colocá-lo entre aspas. Se você estiver usando o Ruby versão 2.2 ou superior, poderá anotá-lo da seguinte maneira:

collection.update_one({ name: "Harriet" }, { "$set": { age: 42 } })

Se você estiver usando uma versão anterior do Ruby, use o símbolo de hashrocket:

collection.update_one({ name: "Harriet" }, { "$set" => { age: 42 } })

As strings e hashrockets citadas para pares de valores-chave funcionarão com qualquer versão do Ruby:

collection.update_one({ "name" => "Harriet" }, { "$set" => { age: 42 } })

Criar documentos

Para inserir documentos em uma coleção, selecione uma coleção no cliente e chame insert_one ou insert_many .

As operações de inserção retornam um objeto Mongo::Operation::Result que fornece informações sobre a própria inserção.

No MongoDB 2.6 e posterior, se a inserção falhar, uma exceção será gerada, pois os comandos de gravação são usados.

No MongoDB 2.4, uma exceção só será gerada se a inserção falhar e owrite concern for 1 ou superior.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
result = client[:artists].insert_one( { :name => 'FKA Twigs' } )
result.n # returns 1, because 1 document was inserted.
result = client[:artists].insert_many([
  { :name => 'Flying Lotus' },
  { :name => 'Aphex Twin' }
])
result.inserted_count # returns 2, because 2 documents were inserted.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test')
price = BSON::Decimal128.new("428.79")
client[:inventory].insert_one({ "_id" => 1,
                                "item" => "26 inch monitor",
                                "price" => price })

{ "_id" : 1, "item" : "26 inch monitor", "price" : NumberDecimal("428.79") }

big_decimal = BigDecimal.new(428.79, 5)
price = BSON::Decimal128.new(big_decimal)
# => BSON::Decimal128('428.79')
price = BSON::Decimal128.from_string("428.79")
# => BSON::Decimal128('428.79')

Cache de consulta

O driver Ruby fornece um cache de query. Quando ativado, o cache de query salvará os resultados das querys de busca e agregação e retornará os resultados salvos quando as mesmas queries forem realizadas novamente.

Para saber mais sobre o cache de query, acesse o tutorial do cache de query.

Leitura

O driver Ruby fornece uma interface fluente para query utilizando o método find na collection. Várias opções estão disponíveis para o método find .

A query é executada lentamente no servidor somente ao iterar os resultados - nesse ponto, a query é despachada e um Mongo::Cursor é retornado.

Para encontrar todos os documentos para um determinado filtro, chame find com a query:

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].find(:name => 'Flying Lotus').each do |document|
  #=> Yields a BSON::Document.
end

Para query documento aninhados, especifique as chaves em ordem aninhada usando notação de ponto.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].find("records.releaseYear": 2008).each do |document|
  #=> Yields a BSON::Document.
end

collection.find(:'$query' => {name: 'Mr. Smith'})
# Equivalent to:
collection.find(name: 'Mr. Smith')
collection.find(:'$query' => {name: 'Mr. Smith'}, :'$sort' => {age: 1})
# Equivalent to:
collection.find(name: 'Mr. Smith').sort(age: 1)

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
documents = client[:artists].find(:name => 'Flying Lotus').skip(10).limit(10)
documents.each do |document|
  #=> Yields a BSON::Document.
end

# All server versions - default explain behavior
client[:artists].find.explain
# MongoDB 3.0 and newer
client[:artists].find.explain(verbosity: :query_planner)
client[:artists].find.explain(verbosity: :execution_stats)
client[:artists].find.explain(verbosity: :all_plans_execution)
# Alternative syntax using camel case
client[:artists].find.explain(verbosity: "queryPlanner")
client[:artists].find.explain(verbosity: "executionStats")
client[:artists].find.explain(verbosity: "allPlansExecution")
# MongoDB 2.6
client[:artists].find.explain(verbose: true)

client[:artists].find({}, session: session).explain
client[:artists].find({}, read: {mode: :secondary_preferred}).explain

client[:artists, read: {mode: :secondary_preferred}].find.explain

client[:artists].find.projection(:name => 1)

client[:artists].find.read(:mode => :secondary_preferred)

client[:artists].find.sort(:name => -1)

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].find(:name => 'Flying Lotus').count_documents

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].estimated_document_count

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].find(:name => 'Flying Lotus').count

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].find.distinct(:name )

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].drop
client[:artists, capped: true, size: 512].create
result = client[:artists].insert_many([
  { :name => 'Flying Lotus' },
  { :name => 'Aphex Twin' }
])
enum = client[:artists].find({}, cursor_type: :tailable_await).to_enum
while true
  doc = enum.next
  # do something
  sleep(1)
end

client = Mongo::Client.new(['localhost:14420'], database: 'music',
  read_concern: {level: :local})
client['collection'].find.to_a
collection = client['collection', read_concern: {level: :majority}]
collection.find.to_a

client.database.command(dbStats: 1, readConcern: {level: :majority})

# Set read preference on a client, used for all operations
client = Mongo::Client.new([ '127.0.0.1:27017' ],
                           read: { mode: :secondary,
                                   tag_sets: [ { 'dc' => 'nyc' } ]
                                  } )
# Set read preference for a given command
client.database.command( { dbStats: 1 }, read: { mode: secondary,
                                                     tag_sets: [ { 'dc' => 'nyc' } ] } )

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
artists = client[:artists]
artists.with(:read => { :mode => :primary_preferred }).find.to_a

client = Mongo::Client.new(
  [ '127.0.0.1:27017' ],
  read: { mode: :secondary, hedge: { enabled: true } },
)

Atualizando

A atualização de documentos é possível executando uma atualização única ou múltipla, ou usando o comando $findAndModify .

update_one

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
artists = client[:artists]
result = artists.find(:name => 'Goldie').update_one("$inc" => { :plays =>  1 } )
result.n # Returns 1.
result = artists.update_one( { :name => 'Goldie' }, { "$inc" => { :plays =>  1 } } )
result.n # Returns 1.

update_many

result = artists.find(:label => 'Hospital').update_many( "$inc" => { :plays =>  1 } )
result.modified_count # Returns the number of documents that were updated.
result = artists.update_many( { :label => 'Hospital' }, { "$inc" => { :plays =>  1 } } )
result.modified_count # Returns the number of documents that were updated.

replace_one

result = artists.find(:name => 'Aphex Twin').replace_one(:name => 'Richard James')
result.modified_count # Returns 1.
result = artists.replace_one( { :name => 'Aphex Twin' }, { :name => 'Richard James' } )
result.modified_count # Returns 1.

Para atualizar documentos e retornar um documento via $findAndModify, use um dos três auxiliares fornecidos: find_one_and_delete, find_one_and_replace ou find_one_and_update. Você pode optar por devolver o documento antes ou depois da modificação ocorrer.

find_one_and_delete

client = Mongo::Client.new( [ '127.0.0.1:27017' ], :database => 'music')
artists = client[:artists]
artists.find(:name => 'José James').find_one_and_delete # Returns the document.

find_one_and_replace

doc = artists.find(:name => 'José James').find_one_and_replace(:name => 'José')
doc # Return the document before the update.
doc = artists.find_one_and_replace({ :name => 'José James' }, { :name => 'José' })
doc # Return the document before the update.
doc = artists.find(:name => 'José James').
  find_one_and_replace( { :name => 'José' }, :return_document => :after )
doc # Return the document after the update.

find_one_and_update

doc = artists.find(:name => 'José James').
  find_one_and_update( '$set' => { :name => 'José' } )
doc # Return the document before the update.
doc = artists.find_one_and_update( { :name => 'José James' }, { '$set' => { :name => 'José' } } )
doc # Return the document before the update.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
artists = client[:artists]
artists.indexes.create_one(name: 1)
# Force the server to use the name index to perform this operation
result = artists.update_one(
  { :name => 'Goldie' },
  { "$inc" => { :plays =>  1 } },
  { hint: { name: 1 } }
)
result.n # Returns 1.

Excluindo

delete_one

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
artists = client[:artists]
result = artists.find(:name => 'Björk').delete_one
result.deleted_count # Returns 1.
result = artists.delete_one(:name => 'Björk')
result.deleted_count # Returns 1.

delete_many

result = artists.find(:label => 'Mute').delete_many
result.deleted_count # Returns the number deleted.
result = artists.delete_many(:label => 'Mute')
result.deleted_count # Returns the number deleted.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
artists = client[:artists]
artists.indexes.create_one(name: 1)
# Force the server to use the name index to perform this operation
result = artists.find(:name => 'Björk').delete_one(hint: { name: 1 })
result.deleted_count # Returns 1.

Escreva preocupação

Todas as operações de gravação no MongoDB são executadas com um write concern, que é o nível de confirmação solicitado do MongoDB para a gravação específica. Mais informações sobre write concerns em geral estão disponíveis no manual do MongoDB.

O driver Ruby suporta a especificação de referência de escrita nos níveis de cliente, collection, sessão (para transação nessa sessão), transação, bucket GridFS e fluxo de gravação, bem como ao emitir comandos manualmente via Database#command.

A partir da versão 2.10 do driver, todos os objeto de driver que aceitam referência de escrita o fazem por meio da opção :write_concern , que deve receber um hash com as opções de referência de escrita. O uso da opção :write está obsoleto. Nas versões 2.9 e inferiores do driver, os objeto client, collection e GridFS usavam opções de write concern na opção :write com objeto de sessão e transação empregando a opção :write_concern .

Abaixo estão alguns exemplos de como passar referência de escrita para objeto de cliente e collection. A opção :write_concern pode ser fornecida ao construir novo objeto de cliente e collection, ou para os métodos #with .

Exemplos de GridFS são fornecidos na página do GridFS .

client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music',
  write_concern: {w: 2})
alt_client = client.with(write_concern: {w: :majority})
collection = client[:artists, write_concern: {w: 3}]
alt_collection = collection.with(write_concern: {w: :majority})
# Uses w: 3
collection.insert_one({name: 'SUN Project'})
# Uses w: :majority
alt_collection.insert_one({name: 'SUN Project'})

As versões 2.9 e anteriores do driver aceitaram referência de escrita no nível do cliente e da collection por meio da opção :write . Esse uso continua a ser suportado para compatibilidade com versões anteriores, mas está obsoleto:

client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music',
  write: {w: 2})
alt_client = client.with(write: {w: :majority})
collection = client[:artists, write: {w: 3}]
alt_collection = collection.with(write: {w: :majority})

Se as opções :write e :write_concern forem fornecidas, seus valores deverão ser idênticos ou uma exceção será gerada:

# OK
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music',
  write_concern: {w: 3}, write: {w: 3})
# Error
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music',
  write_concern: {w: 3}, write: {w: :majority})

Quando os métodos #with são usados para alterar as opções em um cliente ou collection, a última opção fornecida ganha no caso de diferenças de nomeação:

client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music',
  write_concern: {w: 2})
alt_client = client.with(write: {w: 3})
alt_client.options[:write]
# => {"w"=>3}
alt_client.options[:write_concern]
# => nil

Ao usar transações, a write concern só é enviada ao servidor nas operações commit_transaction e abort_transaction acordo com a especificação de transações . A write concern pode ser definida por meio da opção :write_concern em uma chamada with_transaction ou start_transaction , ou por meio da opção default_transaction_options em um objeto de sessão. Se nenhum desses estiver definido, a write concern do cliente será usada; Observe que as transações ignoram as write concerns de collections envolvidas em suas operações. Observe que, ao definir a write concern como uma opção de transação, a opção :write não é reconhecida por nenhuma versão do driver.

client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music',
  write_concern: {w: 2})
collection = client[:artists, write_concern: {w: :majority}]
session = client.start_session
session.with_transaction do
  collection.insert_one({test: 1}, session: session)
  # Uses w: 2 when committing
end
session = client.start_session(default_transaction_options:
  {write_concern: {w: 3})
)
session.with_transaction do
  collection.insert_one({test: 1}, session: session)
  # Uses w: 3 when committing
end
session = client.start_session
session.with_transaction(write_concern: {w: 3}) do
  collection.insert_one({test: 1}, session: session)
  # Uses w: 3 when committing
end

Quando as referências de escrita são herdadas, a herança se aplica a todo o hash da referência de escrita em vez de a elementos individuais. Por exemplo, j: true não é herdado no seguinte caso:

client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music',
  write_concern: {w: 1, j: true})
collection = client[:artists, write_concern: {w: 2}]
collection.write_concern.options
# => #<Mongo::WriteConcern::Acknowledged:0x47289650367880 options={:w=>2}>

Embora as operações CRUD aceitem um hash de opções, elas atualmente não reconhecem a opção :write_concern :

client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music',
  write_concern: {w: 2})
collection = client[:artists, write_concern: {w: :majority}]
# Still uses w: :majority
collection.insert_one({name: 'SUN Project'}, write_concern: {w: 1})

A solução alternativa mais fácil para isso é usar #with para obter uma nova instância de collection com a referência de escrita desejada:

# Uses w: 1
collection.with(write_concern: {w: 1}).insert_one(name: 'SUN Project')

A referência de escrita também pode ser especificada manualmente em Database#command:

client.database.command(create: 'foo-collection', writeConcern: {w: :majority})

Observe que writeConcern aqui é parte da operação em vez de opções, e a sintaxe é o camel case que o MongoDB Server reconhece, não o sublinhado que o driver Ruby usa.

Nomes de campo com pontos/pontos finais (.) e cifrões ($)

A partir da mongo Ruby versão { } do driver 2.18.0, a capacidade de trabalhar com campos que começam com cifrões ($) e campos com pontos/pontos finais (.) está disponível. Na versão 2.17.0 e anteriores do Driver, qualquer tentativa de trabalhar com campos pontilhados ou em dólares resultaria na criação de um erro IllegalKey . Consulte os MongoDB Docs do sobre Nomes de campo com pontos (.) e assinaturas em dólares ($) para obter mais informações sobre como trabalhar com esses tipos de campos.

Uma observação sobre o tipo de símbolo BSON

Como a especificação BSON preteriu o tipo de símbolo BSON, a joia bson serializará os símbolos Ruby em cadeias de caracteres BSON quando usada sozinha. No entanto, para manter a compatibilidade com o conjuntos de dados mais antigos, o driver Ruby substitui esse comportamento para serializar símbolos Ruby como símbolos BSON. Isso é necessário para que seja possível especificar query para documento que contenham símbolos BSON como campo. Apesar disso, novos documentos com campos do tipo símbolo não devem ser armazenados no banco de dados; em vez disso, use campos de string.

Para substituir o comportamento padrão e configurar o driver para codificar valores de símbolo como strings, inclua o seguinte trecho de código em seu projeto:

class Symbol
  def bson_type
    BSON::String::BSON_TYPE
  end
end