Especificar una consulta de documento

Datos de muestra

Los ejemplos de esta guía utilizan el Band Modelo que representa una banda o grupo musical. La definición del modelo Band puede variar en cada sección para demostrar distintas funcionalidades de consulta. Algunas secciones pueden usar otros modelos para demostrar la funcionalidad de consulta.

Sintaxis de campo

La sintaxis de consulta de campos utiliza los hashes básicos de Ruby. Las claves pueden ser símbolos o cadenas y corresponden a los nombres de campo en los documentos de MongoDB.

El siguiente código muestra dos consultas equivalentes que utilizan la sintaxis de consulta de campo para recuperar documentos en los que el valor del campo name es 'Depeche Mode':

Band.where(name: 'Depeche Mode')
Band.where('name' => 'Depeche Mode')

Sintaxis de la API de consulta

Puede especificar un operador de API de consulta en cualquier campo utilizando la sintaxis hash, como lo muestran las siguientes consultas equivalentes:

Band.where(founded: {'$gt' => 1980})
Band.where('founded' => {'$gt' => 1980})

Sintaxis del Operador de Símbolos

Puede especificar operadores de API de consulta como métodos en símbolos para el nombre de campo respectivo, como se muestra en el siguiente código:

Band.where(:founded.gt => 1980)

Campos definidos

Para consultar un campo, no es necesario que este esté en la definición de la clase del modelo. Sin embargo, si un campo está definido en la clase del modelo, Mongoid convierte los valores de la consulta para que coincidan con los tipos de campo definidos al construir la consulta.

El siguiente código especifica un valor de cadena al consultar el campo founded. Dado que el campo founded está definido en la clase del modelo con valores Integer, Mongoid convierte la cadena '2020' en 2020 al realizar la consulta:

Band.where(founded: '2020')

Para obtener más información sobre cómo definir campos en Mongoid, consulte la Guíade tipos de campos.

Valores brutos

Para evitar el comportamiento de coerción de tipo de consulta de Mongoid y consultar directamente el valor tipificado sin formato en la base de datos, envuelva el valor de la consulta en la clase Mongoid::RawValue, como se muestra en el siguiente código:

Band.where(founded: Mongoid::RawValue('2020'))

Alias ​​de campo

Las consultas siguen los nombres de los campos de almacenamiento y los alias de campos que haya configurado en la definición de la clase de modelo.

Los campos id y _id son alias, por lo que puede utilizar cualquiera de los nombres de campo en las consultas:

Band.where(id: '5ebdeddfe1b83265a376a760')
Band.where(_id: '5ebdeddfe1b83265a376a760')

Documentos incrustados

Para consultar los valores de los campos de los documentos incrustados, puede usar la notación de puntos. El siguiente código recupera los documentos cuyo campo name del documento incrustado Manager es 'Smith':

Band.where('manager.name' => 'Smith')

El siguiente código demuestra cómo utilizar un operador de símbolo al realizar consultas en un campo incrustado:

Band.where(:'manager.name'.ne => 'Smith')

Combinaciones de operadores

Los operadores lógicos tienen la misma semántica que los de Active Record.

Cuando se especifican condiciones en el mismo campo varias veces, todas las condiciones se agregan a los criterios, como lo muestran las consultas en el siguiente código:

# Combines as "and"
Band.where(name: 'Swans').where(name: 'Feist')
# Combines as "or"
Band.where(name: 'Swans').or(name: 'Feist')

Las operaciones any_of, none_of, nor y not se comportan de manera similar.

Cuando se utilizan los operadores lógicos and, or y nor, estos operan sobre los criterios desarrollados hasta ese momento:

# "or" applies to the first condition, and the second is combined
# as "and"
Band.or(name: 'Sun').where(label: 'Trust')
# Same as previous example - "where" and "and" are aliases
Band.or(name: 'Sun').and(label: 'Trust')
# Same operator can be stacked any number of times
Band.or(name: 'Sun').or(label: 'Trust')
# The last label condition is added to the top level as "and"
Band.where(name: 'Sun').or(label: 'Trust').where(label: 'Feist')
# Interpreted query:
# {"$or"=>[{"name"=>"Sun"}, {"label"=>"Trust"}], "label"=>"Feist"}

no comportamiento

Puede usar el método not sin argumentos, en cuyo caso niega la siguiente condición especificada. El método not puede llamarse con una o más condiciones hash u objetos Criteria, que se niegan y se añaden a los criterios.

Los siguientes ejemplos demuestran el comportamiento de not:

# "not" negates "where"
Band.not.where(name: 'Best')
# The second "where" is added as "$and"
Band.not.where(name: 'Best').where(label: /Records/)
# "not" negates its argument
Band.not(name: 'Best')

# String negation - uses "$ne"
Band.not.where(name: 'Best')
 
# Regex negation - uses "$not"
Band.not.where(name: /Best/)

De forma similar a and, la operación not niega condiciones individuales para criterios de campo simples. Para condiciones complejas y cuando un campo ya tiene una condición definida, Mongoid emula $not mediante una construcción {'$and' => [{'$nor' => ...}]}, ya que MongoDB admite el operador $not solo por campo, no globalmente:

# Simple condition
Band.not(name: /Best/)
# Complex conditions
Band.where(name: /Best/).not(name: 'Astral Projection')
# Symbol operator syntax
Band.not(:name.ne => 'Astral Projection')

Si está utilizando not con matrices o expresiones regulares, consulte las limitaciones de $not en el manual del servidor.

Estrategias de fusión

Mongoid proporciona las siguientes estrategias de fusión:

• Anulación: la nueva instancia del operador reemplaza cualquier condición existente en el mismo campo utilizando el mismo operador.

• Intersección: Si ya existe una condición que usa el mismo operador en el mismo campo, los valores de la condición existente se intersectan con los valores de la nueva condición y el resultado se almacena como el valor del operador.

• Unión: Si ya existe una condición que utiliza el mismo operador en el mismo campo, los valores de la nueva condición se agregan a los valores de la condición existente y el resultado se almacena como el valor del operador.

El siguiente código demuestra cómo las estrategias de combinación producen criterios utilizando in como operador de ejemplo:

Band.in(name: ['a']).override.in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["b"]}}
Band.in(name: ['a', 'b']).intersect.in(name: ['b', 'c'])
# Interpreted query:
# {"name"=>{"$in"=>["b"]}}
Band.in(name: ['a']).union.in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["a", "b"]}}

La estrategia se solicita llamando a override, intersect o union en una instancia Criteria. La estrategia solicitada se aplica al siguiente método de condición llamado en la query. Si el siguiente método de condición llamado no admite soporte de estrategias de fusión, la estrategia se reinicia, como se muestra en el siguiente ejemplo:

Band.in(name: ['a']).union.ne(name: 'c').in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["a"], "$ne"=>"c"}, "$and"=>[{"name"=>{"$in"=>["b"]}}]}

Dado que ne no admite estrategias de fusión, la estrategia union se ignora y se restablece. Al invocar in por segunda vez, no hay ninguna estrategia activa.

Métodos de operador admitidos

Los siguientes métodos de operador admiten estrategias de fusión:

• all

• in

• nin

El conjunto de métodos podría ampliarse en futuras versiones de Mongoid. Para garantizar la compatibilidad futura, invoque un método de estrategia solo cuando la siguiente llamada al método sea un operador compatible con estrategias de fusión.

Las estrategias de fusión solo se aplican cuando se añaden condiciones mediante los métodos designados. En el siguiente ejemplo, la estrategia de fusión no se aplica porque la segunda condición se añade como where, no mediante in:

Band.in(name: ['a']).union.where(name: {'$in' => 'b'})
# Interpreted query:
# {"foo"=>{"$in"=>["a"]}, "$and"=>[{"foo"=>{"$in"=>"b"}}]}

Expansión del valor del operador

Los métodos de operador que admiten estrategias de fusión toman Array como tipo de valor. Mongoid expande tipos compatibles con Array, como Range, cuando se utilizan con estos métodos de operador.

El siguiente ejemplo demuestra cómo se puede pasar un objeto Range como valor de consulta al utilizar el método in:

Band.in(year: 1950..1960)
# Interpreted query:
# {"year"=>{"$in"=>[1950, 1951, 1952, 1953, 1954, 1955, 1956, 1957, 1958, 1959, 1960]}}

Mongoid envuelve valores distintos deArray en matrices, como se muestra en el siguiente ejemplo:

Band.in(year: 1950)
# Interpreted query: {"year"=>{"$in"=>[1950]}}

Asociaciones

Puede utilizar el método elem_match para hacer coincidir asociaciones integradas.

Este ejemplo utiliza los siguientes modelos que definen una asociación integrada entre Band y Tour:

class Band
    include Mongoid::Document
    field :name, type: String
    embeds_many :tours
end
class Tour
  include Mongoid::Document
  field :city, type: String
  field :year, type: Integer
  embedded_in :band
end

El siguiente código crea un objeto Band y objetos Tour incrustados, luego utiliza el método elem_match para consultar el campo city:

aerosmith = Band.create!(name: 'Aerosmith')
Tour.create!(band: aerosmith, city: 'London', year: 1995)
Tour.create!(band: aerosmith, city: 'New York', year: 1999)
# Returns the "Aerosmith" document
Band.elem_match(tours: {city: 'London'})

Puede utilizar elem_match para query asociaciones anidadas recursivamente, como se muestra en el siguiente ejemplo:

class Tag
    include Mongoid::Document
    field name:, type: String
    recursively_embeds_many
end
# Creates the root Tag
root = Tag.create!(name: 'root')
# Adds embedded Tags
sub1 = Tag.new(name: 'sub_tag_1', child_tags: [Tag.new(name: 'sub_sub_tag_1')])
root.child_tags << sub1
root.child_tags << Tag.new(name: 'sub_tag_2')
root.save!
# Searches for Tag in which one child Tag tame is "sub_tag_1"
Tag.elem_match(child_tags: {name: 'sub_tag_1'})
# Searches for a child Tag in which one child Tag tame is "sub_sub_tag_1"
root.child_tags.elem_match(child_tags: {name: 'sub_sub_tag_1'})

Para obtener más información sobre las asociaciones, consulte la guía de Asociaciones.

Contabilizar documentos

Puede usar los métodos count y estimated_count para contar la cantidad de documentos en una colección.

Puede contar la cantidad de documentos que coinciden con los criterios de filtro utilizando el método count:

# Counts all documents in collection
Band.count
# Counts documents that match criteria
Band.where(country: 'England').count

Puede obtener un número aproximado de documentos en la colección a partir de los metadatos de la colección utilizando el método estimated_count:

Band.estimated_count

El estimated_count método no acepta condiciones de consulta, incluidas las establecidas por un ámbito en el modelo. Si se llama a este método en un modelo con un ámbito predeterminado, primero se debe llamar al unscoped método para deshabilitarlo.

Métodos ordinales

Los métodos descritos en la siguiente lista le permiten seleccionar un resultado específico de la lista de documentos devueltos en función de su posición.

• first: Devuelve el primer documento coincidente. Puede obtener los primeros n documentos pasando un parámetro entero. Este método ordena automáticamente el campo. Consulte las _id líneas 18 -del siguiente código para ver ejemplos.

• last: Devuelve el último documento coincidente. Puede obtener los últimos n documentos pasando un parámetro entero. Este método ordena automáticamente el campo. Consulte la _id línea 11 del siguiente código para ver un ejemplo.

• first_or_create: Devuelve el primer documento coincidente. Si no hay ningún documento coincidente, crea y devuelve uno nuevo guardado.

• first_or_initialize: Devuelve el primer documento coincidente. Si no hay ningún documento coincidente, devuelve uno nuevo.

• second: Retorna el segundo documento coincidente. Utiliza automáticamente una ordenación en el campo _id.

• third: Devuelve el tercer documento coincidente. Ordena automáticamente el campo _id.

• fourth: Devuelve el cuarto documento coincidente. Ordena automáticamente el campo _id.

• fifth: Devuelve el quinto documento coincidente. Ordena automáticamente el campo _id.

• second_to_last: Devuelve el penúltimo documento coincidente. Ordena automáticamente el campo. Consulte la _id línea 14 del siguiente códigopara ver un ejemplo.

• third_to_last: Devuelve el antepenúltimo documento coincidente. Ordena automáticamente el campo _id.

El siguiente código demuestra cómo utilizar algunos métodos descritos en la lista anterior:

1
# Returns the first document in the collection
2
Band.first
3
4
# Returns the first matching document
5
Band.where(founded: {'$gt' => 1980}).first
6
7
# Returns the first two matching documents
8
Band.first(2)
9
10
# Returns the last matching document
11
Band.where(founded: {'$gt' => 1980}).last
12
13
# Returns the second to last document
14
Band.second_to_last

Valores de los campos de la encuesta

Para inspeccionar los valores de campos específicos de documentos en una colección, puede utilizar los siguientes métodos:

• distinctObtiene una lista de valores distintos para un solo campo. Consulte laslíneas 1-7 del siguiente código para ver ejemplos.

• pickObtiene los valores de un documento para los campos proporcionados. Devuelve nil para los campos no definidos o inexistentes. Consulte la línea del siguiente código para ver un ejemplo.10

• pluckObtiene todos los valores del campo proporcionado. Devuelve nil para campos no definidos o inexistentes. Consultela línea del siguiente código para ver un ejemplo.13

• tally: Obtiene un mapeo de valores a recuentos para el campo especificado. Consulta la línea 16 en el siguiente código como ejemplo.

Los métodos anteriores aceptan nombres de campo referenciados mediante notación de puntos, lo que permite referenciar campos en asociaciones incrustadas. También respetan los alias de campo, incluidos los definidos en documentos incrustados.

El siguiente código demuestra cómo utilizar estos métodos:

1
Band.distinct(:name)
2
# Example output: "Ghost Mountain" "Hello Goodbye" "She Said"
3
4
Band.where(:members.gt => 2).distinct(:name)
5
# Example output: "Arctic Monkeys" "The Smiths"
6
7
Band.distinct('tours.city')
8
# Example output: "London" "Sydney" "Amsterdam"
9
10
Band.all.pick(:name)
11
# Example output: "The Smiths"
12
13
Band.all.pluck(:country)
14
# Example output: "England" "Spain" "England" "Japan"
15
16
Band.all.tally(:country)
17
# Example output: ["England",2] ["Italy",3]

Misceláneo

La siguiente lista describe los métodos Mongoid que no encajan en otra categoría:

• each: Itera sobre todos los documentos coincidentes.

# Print each matching document "name" to console
Band.where(:members.gt => 1).each do |band|
  p band.name
end

• exists?: Determina si existen documentos coincidentes y devuelve true si se encuentra al menos un documento coincidente.

# Checks existence of any document
Band.exists?
# Checks existence based on query
Band.where(name: "Le Tigre").exists?
Band.exists?(name: "Le Tigre")
# Checks existence based on "_id" value
Band.exists?('6320d96a3282a48cfce9e72c')
# Always returns false
Band.exists?(false)
Band.exists?(nil)