Especificar una consulta de documento

Datos de muestra

Los ejemplos de esta guía utilizan el Band modelo, lo que representa a una banda o grupo musical. La definición del modelo Band puede ser diferente para cada sección para demostrar diferentes funcionalidades de query. Algunas secciones pueden emplear otros modelos para demostrar la funcionalidad de query.

Sintaxis de campo

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

El siguiente código muestra dos queries equivalentes que utilizan la sintaxis de query 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 Query

Se puede especificar un operador de API de consulta en cualquier campo utilizando la sintaxis de hash, como se muestra en las siguientes consultas equivalentes:

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

Sintaxis del Operador de Símbolos

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

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

Campos definidos

Para hacer una query en un campo, el campo no necesita estar en la definición de la clase modelo. Sin embargo, si un campo está definido en la clase del modelo, Mongoid fuerza los valores de la query para que coincidan con los tipos de campo definidos al construir la query.

El siguiente código especifica un valor de string cuando se consulta en el campo founded. Debido a que el founded campo está definido en la Integer clase de modelo para tener valores, Mongoid convierte la cadena '2020' en 2020 al realizar la query:

Band.where(founded: '2020')

Para obtener más información sobre cómo definir campos en Mongoid, consulte la Usa los tipos de campo BSON guía.

Valores brutos

Para evitar el comportamiento de coerción de tipo de consulta de Mongoid y consultar directamente el valor de tipo bruto en la base de datos, encapsula 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 podrías haber configurado en la definición de la clase del modelo.

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

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

Documentos incrustados

Para consultar acerca de los valores de los campos de documentos incrustados, puedes utilizar la notación de puntos. El siguiente código recupera los documentos en los que el campo name del documento incorporado Manager es 'Smith':

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

El siguiente código demuestra cómo usar un operador de símbolo al consultar un campo integrado:

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 añaden a los criterios, como demuestra las consultas del 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 usas los operadores lógicos and, or, y nor, estos actúan sobre los criterios establecidos hasta ese punto:

# "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

Puedes utilizar el método not sin argumentos, en cuyo caso niega la siguiente condición que se especifique. El método not puede llamarse con una o más condiciones hash u objetos Criteria, los cuales 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 manera 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 el uso de un constructo {'$and' => [{'$nor' => ...}]}, porque MongoDB solo admite el operador $not por campo, en lugar de 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 utilizas not con arreglos o expresiones regulares, consulta las limitaciones de $not en el manual del servidor.

Estrategias de fusión

Mongoid proporciona las siguientes estrategias de fusión:

• Supersede: la nueva instancia del operador sustituye 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 suman a los valores de la condición existente y el resultado se almacena como el valor del operador.

El siguiente código muestra cómo las estrategias de fusión generan 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"]}}]}

Debido a que ne no admite estrategias de fusión, la estrategia union se ignora y restablece. Entonces, cuando in se invoca por segunda vez, no hay una 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, invoca un método de estrategia solo cuando la próxima llamada de método sea un operador que admita estrategias de fusión.

Las estrategias de combinación se aplican solo 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 utilizando 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 utilizan Array como su tipo de valor. Mongoid amplía los tipos compatibles con Array, como un Range, cuando se utilizan con estos métodos operadores.

El siguiente ejemplo demuestra cómo puedes pasar un objeto Range como valor de query 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 que no sonArray en arreglos, como se muestra en el siguiente ejemplo:

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

Asociaciones

Puedes utilizar el método elem_match para igualar asociaciones anidadas.

Este ejemplo utiliza los siguientes modelos que definen una asociación embebida 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 e incrusta objetos Tour, luego utiliza el método elem_match para hacer consultas en 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 las guías de Asociaciones referenciadas y Asociaciones integradas.

Contabilizar documentos

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

Puedes contar el número de documentos que coinciden con criterios de filtro usando el método count:

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

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

Band.estimated_count

El método estimated_count no acepta condiciones de query, incluidas las condiciones establecidas por un scope en el modelo. Si está llamando este método en un modelo con un alcance por defecto, debe llamar primero al método unscoped para desactivar dicho alcance.

Métodos ordinales

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

• firstDevuelve el primer documento coincidente. Puede obtener los primeros n documentos pasando un parámetro con valor entero. Este método utiliza automáticamente una ordenación en el campo _id. Consulte las líneas 1-8 en el siguiente código para ver ejemplos.

• lastDevuelve el último documento coincidente. Puede obtener los últimos n documentos pasando un parámetro entero. Este método utiliza automáticamente una ordenación en el campo _id. Consulta la línea 11 en el siguiente código para un ejemplo.

• first_or_createDevuelve el primer documento que coincida. Si no hay ningún documento que coincida, crea y devuelve uno recién guardado.

• first_or_initializeDevuelve el primer documento coincidente. Si ningún documento coincide, 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. Utiliza automáticamente una ordenación en el campo _id.

• fourth: Devuelve el cuarto documento coincidente. Utiliza automáticamente una ordenación en el campo _id.

• fifthDevuelve el quinto documento de coincidencia. Utiliza automáticamente una ordenación en el campo _id.

• second_to_lastDevuelve el penúltimo documento coincidente. Utiliza automáticamente un orden en el campo _id. Consulte la línea 14 en el siguiente código para ver un ejemplo.

• third_to_last: Devuelve el tercer documento coincidente antes del último. Utiliza automáticamente una ordenación en 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 campo de la encuesta

Para inspeccionar los valores de los campos especificados de los documentos en una colección, puedes usar los siguientes métodos:

• distinct: Obtiene una lista de valores distintos para un campo único. Consulta las líneas 1-7 en el siguiente código para ver ejemplos.

• pick: Obtiene los valores de un documento para los campos proporcionados. Devuelve nil para campos no establecidos y para campos inexistentes. Consulte la línea 10 en el siguiente código para ver un ejemplo.

• pluckObtiene todos los valores para el campo proporcionado. Devuelve nil para los campos no establecidos y para los campos inexistentes. Vea la línea 13 en el siguiente código como ejemplo.

• 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 campos referenciados mediante la notación de puntos, lo que permite referenciar campos en asociaciones anidadas. 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 métodos de 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?: Determinar si existen documentos coincidentes, devolviendo 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)