Lenguaje de consulta de reino

Los SDK de dispositivos Atlas están obsoletos. Consulte Página de desuso para más detalles.

El lenguaje de consulta de dominio (RQL) es un lenguaje de consulta basado en cadenas que restringe las búsquedas al recuperar objetos de un dominio. Los métodos específicos del SDK pasan las consultas al motor de consultas de dominio, que recupera los objetos coincidentes del dominio. La sintaxis del lenguaje de consulta de dominio se basa en Predicado NS.

Las consultas evalúan un predicado para cada objeto de la colección consultada. Si el predicado se resuelve como true, la colección de resultados incluye el objeto.

Puedes usar el lenguaje de consulta de Realm en la mayoría de los SDK de Realm con sus métodos de filtro o consulta. El SDK de Swift es la excepción, ya que utiliza la API de consulta NSPredicate. Algunos SDK también admiten API idiomáticas para consultar los reinos en su lenguaje.

Consulta con SDK de Realm

Para obtener más información sobre los métodos específicos del SDK para consultar dominios, consulte la documentación de su SDK:

Filtrar y ordenar resultados - SDK de Flutter

Filtrar datos - SDK de Kotlin

Motor de consultas - SDK .NET

Actualmente, el SDK de C++ implementa solo un subconjunto de RQL. Para ver ejemplos de consultas de Realm en el SDK de C++, consulte:

Filtrar datos - SDK de C++

Nota

El SDK de Swift no es compatible con el lenguaje de consulta Realm

El SDK de Swift no admite consultas con el lenguaje de consulta Realm. En su lugar, puede usar NSPredicate para consultar Realm. Para ver ejemplos de consultas de Realm en el SDK de Swift, consulte Filtrar datos - SDK de Swift.

También puedes usar el lenguaje de consulta de Realm para buscar datos en Realm Studio. Realm Studio es una herramienta visual para ver, editar y diseñar archivos de Realm.

Ejemplos en esta página

Muchos de los ejemplos de esta página utilizan un conjunto de datos simple para una aplicación de lista de tareas. Los dos tipos de objeto Realm son Project y Item.

Un Item tiene un nombre, el nombre del asignado y una marca de finalización. También hay un número arbitrario para la prioridad (cuanto más alto, más importante) y un recuento de minutos dedicados a trabajar en él.
Un Project tiene cero o más Items y una cuota opcional para el número mínimo de elementos por hacer que se espera completar.

Vea el esquema de estas dos clases, Project y Item, a continuación:

public class Item extends RealmObject {
  ObjectId id = new ObjectId();
  String name;
  Boolean isComplete = false;
  String assignee;
  Integer priority = 0;
  Integer progressMinutes = 0;
  @LinkingObjects("items")
  final RealmResults<Project> projects = null;
}
public class Project extends RealmObject {
  ObjectId id = new ObjectId();
  String name;
  RealmList<Item> items;
  Integer quota = null;
}

open class Item(): RealmObject() {
  var id: ObjectId = new ObjectId()
  @FullText
  lateinit var name: String
  var isComplete: Boolean = false
  var assignee: String? = null
  var priority: Int = 0
  var progressMinutes: Int = 0
}
open class Project(): RealmObject() {
  var id: ObjectId = new ObjectId()
  lateinit var name: String
  lateinit var items: RealmList<Item>
  var quota: Int? = null
}

public class Item : RealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public ObjectId Id { get; set; } = ObjectId.GenerateNewId();
    [MapTo("name")]
    [Indexed(IndexType.FullText)]
    public string Name { get; set; }
    [MapTo("isComplete")]
    public bool IsComplete { get; set; } = false;
    [MapTo("assignee")]
    public string Assignee { get; set; }
    [MapTo("priority")]
    public int Priority { get; set; } = 0;
    [MapTo("progressMinutes")]
    public int ProgressMinutes { get; set; } = 0;
    [MapTo("projects")]
    [Backlink(nameof(Project.Items))]
    public IQueryable<Project> Projects { get; }
}
public class Project : RealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public ObjectId Id { get; set; } = ObjectId.GenerateNewId();
    [MapTo("name")]
    public string Name { get; set; }
    [MapTo("items")]
    public IList<Item> Items { get; }
    [MapTo("quota")]
    public int Quota { get; set; }
}

const ItemModel = {
  name: "Item",
  properties: {
    id: "objectId",
    name: {type: "string", indexed: "full-text"},
    isComplete: { type: "bool", default: false },
    assignee: "string?",
    priority: {
      type: "int",
      default: 0,
    },
    progressMinutes: {
      type: "int",
      default: 0,
    },
    projects: {
      type: "linkingObjects",
      objectType: "Project",
      property: "items",
    },
  },
  primaryKey: "id",
};
const ProjectModel = {
  name: "Project",
  properties: {
    id: "objectId",
    name: "string",
    items: "Item[]",
    quota: "int?",
  },
  primaryKey: "id",
};

const ItemModel = {
  name: "Item",
  properties: {
    id: "objectId",
    name: {type: "string", indexed: "full-text"},
    isComplete: { type: "bool", default: false },
    assignee: "string?",
    priority: {
      type: "int",
      default: 0,
    },
    progressMinutes: {
      type: "int",
      default: 0,
    },
    projects: {
      type: "linkingObjects",
      objectType: "Project",
      property: "items",
    },
  },
  primaryKey: "id",
};
const ProjectModel = {
  name: "Project",
  properties: {
    id: "objectId",
    name: "string",
    items: "Item[]",
    quota: "int?",
  },
  primaryKey: "id",
};

class Item(): RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    @FullText
    var name: String = ""
    var isComplete: Boolean = false
    var assignee: String? = null
    var priority: Int = 0
    var progressMinutes: Int = 0
}
class Project(): RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var items: RealmList<Item> = realmListOf<Item>()
    var quota: Int? = null
}

part 'models.realm.dart';
@RealmModel()
class _Project {
  @MapTo("_id")
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late List<_Item> items;
  int? quota;
}
@RealmModel()
class _Item {
  @MapTo("_id")
  @PrimaryKey()
  late ObjectId id;
  @Indexed(RealmIndexType.fullText)
  late String name;
  bool isComplete = false;
  String? assignee;
  int priority = 0;
  int progressMinutes = 0;
}

Expresiones

Los filtros consisten en expresiones en un predicado. Una expresión consiste en uno de los siguientes elementos:

El nombre de una propiedad del objeto que se está evaluando actualmente.
Un operador y hasta dos expresiones de argumento. Por ejemplo, en la expresión A + B, A + B es una expresión, pero A y B también son expresiones de argumento para el operador +.
Un valor, como una cadena ('hello') o un número (5).

"progressMinutes > 1 AND assignee == $0", "Ali"

Consultas parametrizadas

Cree consultas parametrizadas para interpolar variables en sentencias preparadas del lenguaje de consulta de Realm. La sintaxis para las variables interpoladas es $<int>, comenzando en 0. Pase los argumentos posicionales como argumentos adicionales a los métodos del SDK de Realm que usan el lenguaje de consulta de Realm.

Incluya solo un parámetro con $0.

"progressMinutes > 1 AND assignee == $0", "Ali"

Incluya múltiples parámetros con números enteros ascendentes que comiencen en $0.

"progressMinutes > $0 AND assignee == $1", 1, "Alex"

Formatos de consulta

La siguiente tabla muestra cómo se debe formatear una consulta cuando se serializa y parametriza para los siguientes tipos de datos:

Tipo	Ejemplo parametrizado	Ejemplo serializado	Nota
Booleano	"configuración == $0", falso	"configuración == falso"	`true` o `false` valores.
String	"nombre == $0", "George"	"nombre == 'George'"	Se aplica a los tipos de datos `string` y `char`.
Número	"edad > $0", 5.50	"edad > 5.50"	Se aplica a los tipos de datos `int`, `short`, `long`, `double`, `Decimal128` y `float`.
fecha	"fecha < $0", objeto de fecha	"date < 2021-02-20@17:30:15:0"	Para consultas de fecha parametrizadas, debe pasar un objeto de fecha. Para consultas de fecha serializadas, puede representar la fecha en los siguientes formatos: Como fecha y hora explícitas: AAAA-MM-DD@HH:mm:ss:nn (año-mes-día@horas:minutos:segundos:nanosegundos) Como un `datetime` relativo a la época de Unix- Ts:n (T, designa el inicio del tiempo;, `s` segundos;, `n` nanosegundos) Objeto parametrizado `Date`
ObjectID	"_id == $0", oidValue	"_id == oid(507f1f77bcf86cd799439011)"	Para consultas ObjectId parametrizadas, debe pasar un ObjectId. Para consultas ObjectId serializadas, la representación de cadena es `oid(<ObjectId String>)`.
UUID	"id == $0", valorUuid	"id == uuid(d1b186e1-e9e0-4768-a1a7-c492519d47ee)"	Para consultas UUID parametrizadas, debe pasar un UUID. Para consultas UUID serializadas, la representación de cadena es `uuid(<UUID String>)`.
Binario	"valor == $0", "binario"	"valor == 'binario'"	Para caracteres ASCII, RQL serializa el valor binario como una cadena, entre comillas. Para caracteres no imprimibles, RQL serializa el valor binario a un valor base 64.
Lista	"CUALQUIER artículo.nombre == {$0, $1}", "leche", "pan"	"CUALQUIER artículo.nombre == {'leche', 'pan'}"	Se aplica a listas, colecciones y conjuntos. Se debe usar un valor parametrizado para cada miembro de la lista.
Objeto de reino	"CUALQUIER artículo == $0", obj("Artículo", oid(6489f036f7bd0546377303ab))	"CUALQUIER elemento == obj('Ítem', oid(6489f036f7bd0546377303ab))"	Para pasar un RealmObject, necesita la clase y la clave principal del objeto.

Notación de puntos

Al referirse a la propiedad de un objeto, se puede utilizar la notación de puntos para referirse a las propiedades secundarias de ese objeto. Incluso se puede hacer referencia a las propiedades de objetos incrustados y relaciones con la notación de puntos.

Por ejemplo, considere una consulta sobre un objeto con la propiedad workplace que hace referencia a un objeto Workplace. Este objeto tiene una propiedad de objeto incrustada, address. Puede encadenar notaciones de punto para hacer referencia a la propiedad de código postal de esa dirección:

"workplace.address.zipcode == 10019"

Tipo nulo

El lenguaje de consulta Realm incluye el tipo nil para representar un puntero nulo. Puede hacer referencia a nil directamente en sus consultas o con una consulta parametrizada. Si utiliza una consulta parametrizada, cada SDK asigna su puntero nulo correspondiente a nil.

"assignee == nil"

// comparison to language null pointer
"assignee == $0", null

Operadores de comparación

La operación más sencilla en una búsqueda es comparar valores.

Importante

Los tipos deben coincidir

El tipo en ambos lados del operador debe ser equivalente. Por ejemplo, comparar un ObjectId con una cadena generará un error de precondición con un mensaje como este:

"Expected object of type object id for property 'id' on object of type
'User', but received: 11223344556677889900aabb (Invalid value)"

Puede comparar cualquier tipo numérico con cualquier otro tipo numérico, incluidos decimal, float y Decimal128.

Operador	Descripción
`BETWEEN {number1, number2}`	Se evalúa como `true` si la expresión numérica o de fecha de la izquierda se encuentra dentro o es igual al rango de la derecha. Para las fechas, se evalúa como `true` si la fecha de la izquierda está dentro del rango de la derecha.
`==`, `=`	Se evalúa como `true` si la expresión de la izquierda es igual a la expresión de la derecha.
`>`	Se evalúa como `true` si la expresión numérica o de fecha de la izquierda es mayor que la de la derecha. Para las fechas, se evalúa como `true` si la fecha de la izquierda es posterior a la de la derecha.
`>=`	Se evalúa como `true` si la expresión numérica o de fecha de la izquierda es mayor o igual que la expresión numérica o de fecha de la derecha. Para las fechas, se evalúa como `true` si la fecha de la izquierda es posterior o igual a la de la derecha.
`IN`	Se evalúa como `true` si la expresión de la izquierda está en la lista de la derecha. Esto equivale a `== ANY` y se utiliza como abreviatura de este último.
`<`	Se evalúa como `true` si la expresión numérica o de fecha de la izquierda es menor que la de la derecha. Para las fechas, se evalúa como `true` si la fecha de la izquierda es anterior a la de la derecha.
`<=`	Se evalúa como `true` si la expresión numérica de la izquierda es menor o igual que la de la derecha. Para las fechas, se evalúa como `true` si la fecha de la izquierda es anterior o igual a la de la derecha.
`!=`, `<>`	Se evalúa como `true` si la expresión de la izquierda no es igual a la expresión de la derecha.

Ejemplo

El siguiente ejemplo utiliza los operadores de comparación de Realm Query Language para:

Encuentre elementos de tarea de alta prioridad comparando el valor de la propiedad priority con un número umbral, por encima del cual la prioridad puede considerarse alta.
Encuentre elementos de tareas pendientes de larga ejecución viendo si la propiedad progressMinutes está en un valor determinado o por encima de él.
Encuentre elementos de tareas pendientes no asignados buscando elementos donde la propiedad assignee sea igual a null.
Encuentre elementos por hacer dentro de un cierto rango de tiempo buscando elementos donde la propiedad progressMinutes esté entre dos números.
Busca elementos pendientes con una cantidad determinada de progressMinutes de la lista dada.

  // Find high priority to-do items by comparing the value of the ``priority``
  // property value with a threshold number, above which priority can be considered high.
  "priority > $0", 5
  // Find long-running to-do items by seeing if the progressMinutes property is at or above a certain value.
  "progressMinutes > $0", 120
  // Find unassigned to-do items by finding items where the assignee property is equal to null.
  "assignee == $0", null
  // Find to-do items within a certain time range by finding items 
  // where the progressMinutes property is between two numbers.
  "progressMinutes BETWEEN { $0 , $1 }", 30, 60
  // Find to-do items with a certain amount of progressMinutes from the given list.
  "progressMinutes IN { $0, $1, $2, $3, $4, $5 }", 10, 20, 30, 40, 50, 60

Operadores lógicos

Crear predicados compuestos utilizando operadores lógicos.

Operador	Descripción
`AND` `&&`	Se evalúa como `true` si las expresiones de la izquierda y la derecha son `true`.
`NOT` `!`	Niega el resultado de la expresión dada.
`OR` `\|\|`	Se evalúa como `true` si alguna expresión devuelve `true`.

Ejemplo

Podemos usar los operadores lógicos del lenguaje de consulta para encontrar todas las tareas pendientes completadas de Ali. Es decir, buscamos todos los elementos donde el valor de la propiedad assignee es igual a 'Ali' y el valor de la propiedad isComplete es true:

"assignee == $0 AND isComplete == $1", "Ali", true

Operadores de String

Compare valores de cadena con estos operadores. Los comodines tipo expresiones regulares ofrecen mayor flexibilidad en la búsqueda.

Nota

Puede utilizar los siguientes modificadores con los operadores de cadena:

[c] por no distinguir entre mayúsculas y minúsculas.
```
"name CONTAINS[c] $0", 'a'
```

Operador	Descripción
`BEGINSWITH`	Se evalúa como `true` si la expresión de cadena de la izquierda comienza con la expresión de cadena de la derecha. Es similar a `contains`, pero solo coincide si la expresión de cadena de la derecha se encuentra al principio de la expresión de cadena de la izquierda.
`CONTAINS`	Se evalúa como `true` si la expresión de cadena de la derecha se encuentra en cualquier lugar de la expresión de cadena de la izquierda.
`ENDSWITH`	Se evalúa como `true` si la expresión de cadena de la izquierda termina con la expresión de cadena de la derecha. Es similar a `contains`, pero solo coincide si la expresión de cadena de la izquierda se encuentra al final de la expresión de cadena de la derecha.
`LIKE`	Se evalúa como `true` si la expresión de cadena de la izquierda coincide con la expresión de cadena comodín de la derecha. Una expresión de cadena comodín es una cadena que utiliza caracteres normales con dos caracteres comodín especiales: El comodín `*` coincide con cero o más de cualquier carácter El comodín `?` coincide con cualquier carácter. Por ejemplo, la cadena comodín "d?g" coincide con "perro", "dig" y "dug", pero no con "ding", "dg" o "un perro".
`==`, `=`	Se evalúa como `true` si la cadena de la izquierda es lexicográficamente igual a la cadena de la derecha.
`!=`, `<>`	Se evalúa como `true` si la cadena de la izquierda no es lexicográficamente igual a la cadena de la derecha.

Ejemplo

Se utilizan los operadores de string del motor de query para encontrar lo siguiente:

Proyectos con un nombre que empieza con la letra 'e'
Proyectos con nombres que contienen 'ie'

  "name BEGINSWITH[c] $0", 'e'
  "name CONTAINS $0", 'ie'

Operadores ObjectId y UUID

Consulta los ObjectIds y UUID de BSON. Estos tipos de datos se utilizan a menudo como claves principales.

Para consultar con ObjectIds, utilice una consulta parametrizada. Pase como argumento el ObjectId o UUID que consulta.

"_id == $0", oidValue

También puedes poner una representación de cadena del ObjectId que estás evaluando en oid(<ObjectId String>).

"_id == oid(6001c033600510df3bbfd864)"

Para realizar consultas con UUID, coloque una representación de cadena del UUID que está evaluando en uuid(<UUID String>).

"id == uuid(d1b186e1-e9e0-4768-a1a7-c492519d47ee)"

Operador	Descripción
`==`, `=`	Se evalúa como `true` si el valor de la izquierda es igual al valor de la derecha.
`!=`, `<>`	Se evalúa como `true` si el valor de la izquierda no es igual al valor de la derecha.

Operadores aritméticos

Realizar operaciones aritméticas básicas en un lado de una expresión RQL al evaluar tipos de datos numéricos.

  "2 * priority > 6"
  // Is equivalent to
  "priority >= 2 * (2 - 1) + 2"

También puedes utilizar varias propiedades de objetos juntas en una operación matemática.

"progressMinutes * priority == 90"

Operador	Descripción
`*`	Multiplicación.
`/`	División.
`+`	Suma.
`-`	Sustracción.
`()`	Agrupar expresiones juntas.

Operador de tipo

Comprueba el tipo de una propiedad con el operador @type. Este operador solo se puede usar con tipos y diccionarios mixtos.

Evalúe la propiedad con una representación de cadena del nombre del tipo de dato. Consulte la documentación del SDK para obtener información sobre la asignación de los tipos de datos del lenguaje del SDK a los tipos de datos de Realm.

Operador	Descripción
`@type`	Comprueba si el tipo de una propiedad es el nombre de la propiedad como cadena. Usa `==` y `!=` para comparar si son iguales.

  "mixedType.@type == 'string'"
  "mixedType.@type == 'bool'"

Operadores de diccionario

Compare los valores del diccionario utilizando estos operadores de diccionario.

Operador	Descripción
`@values`	Devuelve objetos que tienen el valor especificado en la expresión de la derecha.
`@keys`	Devuelve objetos que tienen la clave especificada en la expresión de la derecha.
`@size`, `@count`	El número de elementos de un diccionario.
`Dictionary['key']`	Acceder al valor de una clave de un diccionario.
`ALL \| ANY \| NONE <property>.@type`	Comprueba si el diccionario contiene propiedades de cierto tipo.

También puede usar operadores de diccionario junto con operadores de comparación para filtrar objetos según sus claves y valores. Los siguientes ejemplos muestran cómo usar operadores de diccionario con operadores de comparación. Todos los ejemplos consultan una colección de objetos Realm con una propiedad de diccionario dict llamada.

Ejemplo

Los siguientes ejemplos utilizan varios operadores de diccionario.

  // Evaluates if there is a dictionary key with the name 'foo'
  "ANY dict.@keys == $0", 'foo'
  // Evaluates if there is a dictionary key with key 'foo' and value 'bar
  "dict['foo'] == $0", 'bar'
  // Evaluates if there is greater than one key-value pair in the dictionary
  "dict.@count > $0", 1
  // Evaluates if dictionary has property of type 'string'
  "ANY dict.@type == 'string'"
  // Evaluates if all the dictionary's values are integers
  "ALL dict.@type == 'bool'"
  // Evaluates if dictionary does not have any values of type int
  "NONE dict.@type == 'double'"
  // ANY is implied.
  "dict.@type == 'string'"

Operadores de fecha

Consultar tipos de fecha en un reino.

Generalmente, debe utilizar una consulta parametrizada para pasar un tipo de datos de fecha del lenguaje SDK que está utilizando a una consulta.

"timeCompleted < $0", someDate

También puede especificar fechas de las dos maneras siguientes:

Como fecha específica (en UTC): YYYY-MM-DD@HH:mm:ss:nnnnnnnnnn (año-mes-día@horas:minutos:segundos:nanosegundos), UTC. También puede usar T en lugar de @ para separar la fecha de la hora.
Como tiempo en segundos desde la época Unix Ts:n-, donde T designa el inicio del tiempo, s es el número de segundos y n es el número de nanosegundos.

La fecha admite operadores de comparación.

Ejemplo

El siguiente ejemplo muestra cómo utilizar una consulta parametrizada con un objeto de fecha:

var date = new Date("2021-02-20@17:30:15:0");
  "timeCompleted > $0", date

Operadores agregados

Aplica un operador de agregación a una propiedad de colección de un objeto Realm. Los operadores de agregación recorren una colección y la reducen a un único valor.

Operador	Descripción
`@avg`	Evalúa el valor promedio de una propiedad numérica dada en una colección. Si algún valor es `null`, no se contabiliza en el resultado.
`@count`	Se evalúa como el número de objetos en la colección dada.
`@max`	Se evalúa como el valor más alto de una propiedad numérica dada en una colección. Los valores `null` se ignoran.
`@min`	Se evalúa como el valor más bajo de una propiedad numérica dada en una colección. Los valores `null` se ignoran.
`@sum`	Se evalúa como la suma de una propiedad numérica dada en una colección, excluyendo los valores `null`.

Ejemplo

Todos estos ejemplos consultan proyectos que contienen elementos de tareas pendientes que cumplen estos criterios:

Proyectos con prioridad de elemento promedio superior a 5.
Proyectos con un elemento cuya prioridad es menor que 5.
Proyectos con un elemento cuya prioridad es mayor que 5.
Proyectos con más de 5 elementos.
Proyectos con elementos de larga duración.

var priorityNum = 5;
  "items.@avg.priority > $0", priorityNum
  "items.@max.priority < $0", priorityNum
  "items.@min.priority > $0", priorityNum
  "items.@count > $0", 5
  "items.@sum.progressMinutes > $0", 100

Operadores de cobranza

Un operador de colección permite consultar las propiedades de lista dentro de una colección de objetos. Los operadores de colección filtran una colección aplicando un predicado a cada elemento de una propiedad de lista dada del objeto. Si el predicado devuelve verdadero, el objeto se incluye en la colección de salida.

Operador	Descripción
`ALL`	Devuelve objetos donde el predicado evalúa como `true` para todos los objetos de la colección.
`ANY`, `SOME`	Devuelve objetos donde el predicado evalúa a `true` para cualquier objeto de la colección.
`NONE`	Devuelve objetos donde el predicado se evalúa como falso para todos los objetos de la colección.

Ejemplo

Este ejemplo utiliza operadores de colección para buscar proyectos que contengan elementos de tareas pendientes que coincidan con determinados criterios:

  // Projects with no complete items.
  "NONE items.isComplete == $0", true
  // Projects that contain a item with priority 10
  "ANY items.priority == $0", 10
  // Projects that only contain completed items
  "ALL items.isComplete == $0", true
  // Projects with at least one item assigned to either Alex or Ali
  "ANY items.assignee IN { $0 , $1 }", "Alex", "Ali"
  // Projects with no items assigned to either Alex or Ali
  "NONE items.assignee IN { $0 , $1 }", "Alex", "Ali"

Comparaciones de listas

Puede utilizar operadores de comparación y operadores de colección para filtrar según listas de datos.

Puedes comparar cualquier tipo de lista válida. Esto incluye:

colecciones de objetos Realm, que le permiten filtrar con respecto a otros datos en el reino.
```
"oid(631a072f75120729dc9223d9) IN items.id"
```
Listas definidas directamente en la consulta, que permiten filtrar datos estáticos. Las listas estáticas se definen como una lista de valores literales separados por comas, encerrados entre llaves de apertura ({) y cierre (}).
```
"priority IN {0, 1, 2}"
```

objetos de lista nativos pasados en una expresión parametrizada, que le permiten pasar datos de la aplicación directamente a sus consultas.

const ids = [
  new BSON.ObjectId("631a072f75120729dc9223d9"),
  new BSON.ObjectId("631a0737c98f89f5b81cd24d"),
  new BSON.ObjectId("631a073c833a34ade21db2b2"),
];
const parameterizedQuery = realm.objects("Item").filtered("id IN $0", ids);

Si no define un operador de colección, una expresión de lista toma como valor predeterminado el operador ANY.

Ejemplo

Estas dos consultas de lista son equivalentes:

age == ANY {18, 21}
age == {18, 21}

Ambas consultas devuelven objetos con una propiedad de edad igual a 18 o 21. También se puede hacer lo contrario, devolviendo objetos solo si la edad no es igual a 18 o 21:

age == NONE {18, 21}

La siguiente tabla incluye ejemplos que ilustran cómo los operadores de colección interactúan con listas y operadores de comparación:

expresión	¿Fósforo?	Razón
`ANY {1, 2, 3} > ALL {1, 2}`	true	Un valor a la izquierda (3) es mayor que algún valor a la derecha (tanto 1 como 2)
`ANY {1, 2, 3} == NONE {1, 2}`	true	3 no coincide con ninguno de los dos: 1 o 2
`ANY {4, 8} == ANY {5, 9, 11}`	false	Ni 4 ni 8 coinciden con ningún valor de la derecha (5, 9 o 11)
`ANY {1, 2, 7} <= NONE {1, 2}`	true	Un valor a la izquierda (7) no es menor o igual que 1 y 2
`ALL {1, 2} IN ANY {1, 2, 3}`	true	Cada valor de la izquierda (1 y 2) es igual a 1, 2 o 3
`ALL {3, 1, 4, 3} == NONE {1, 2}`	false	1 coincide con un valor de la lista NINGUNO (1 o 2)
`ALL {} in ALL {1, 2}`	true	Una lista vacía coincide con todas las listas
`NONE {1, 2, 3, 12} > ALL {5, 9, 11}`	false	12 es mayor que todos los valores de la derecha (5, 9 y 11)
`NONE {4, 8} > ALL {5, 9, 11}`	true	4 y 8 son ambos menores que cierto valor a la derecha (5, 9 o 11)
`NONE {0, 1} < NONE {1, 2}`	true	0 y 1 son ambos menores que ninguno de 1 y 2

Full Text Search

Puede utilizar RQL para consultar propiedades que tengan una anotación de búsqueda de texto completo (FTS). FTS admite búsquedas de coincidencia booleana de palabras, en lugar de búsquedas por relevancia. Para obtener información sobre cómo habilitar el FTS en una propiedad, consulte la documentación de FTS correspondiente a su SDK:

SDK de Flutter
Kotlin SDK
Kit de desarrollo de software .NET
Node.js SDK
SDK de React Native
Swift SDK aún no admite la búsqueda de texto completo.

Para consultar estas propiedades, utilice el predicado TEXT en su consulta.

Puede buscar palabras o frases completas o limitar sus resultados con los siguientes caracteres:

Excluye los resultados de una palabra colocando el carácter - delante de la palabra.
Especifique prefijos colocando el carácter * al final. Actualmente no se admite la búsqueda de sufijos.

En el siguiente ejemplo, consultamos la propiedad Item.name:

    // Filter for items with 'write' in the name
    "name TEXT $0", "write"
    // Find items with 'write' but not 'tests' using '-'
    "name TEXT $0", "write -tests"
    // Find items starting with 'wri-' using '*'
    "name TEXT $0", "wri*"

Detalles del tokenizador de búsqueda de texto completo

Los índices de búsqueda de texto completo (FTS) admiten:

Los tokens no distinguen entre mayúsculas y minúsculas ni entre signos diacríticos.
Los tokens solo pueden contener caracteres ASCII y el suplemento latino1 (idiomas occidentales). Todos los demás caracteres se consideran espacios en blanco.
Las palabras separadas por un guion (-) se dividen en dos tokens. Por ejemplo, full-text se divide en full y text.

Query geoespacial

Puede realizar consultas sobre datos geoespaciales con el operador geoWithin. El operador geoWithin toma el par latitud/longitud de la propiedad coordinates de un objeto incrustado personalizado y una forma geoespacial. El operador comprueba si el punto cordinates está contenido dentro de la forma geoespacial.

Las siguientes formas geoespaciales son compatibles para realizar consultas:

GeoCircle
GeoBox
GeoPolygon

Para query datos geoespaciales:

Crea un objeto con una propiedad que contenga los datos geoespaciales incorporados.
Define la forma geoespacial para establecer el límite de la consulta.
Consulta utilizando el operador RQL geoWithin.

En la siguiente consulta, verificamos que las coordenadas de la propiedad location incrustada estén contenidas dentro de la forma GeoCircle, smallCircle:

"location geoWithin $0", smallCircle

Para obtener más información sobre cómo definir formas y objetos geoespaciales con datos geoespaciales integrados, consulte la documentación geoespacial de su SDK:

Consultas de backlinks

Un vínculo de retroceso es un enlace de relación inversa que permite buscar objetos que hacen referencia a otro objeto. Los vínculos de retroceso utilizan las relaciones a uno y a muchos definidas en los esquemas de objetos, pero en sentido inverso. Cada relación definida en el esquema tiene implícitamente un vínculo de retroceso correspondiente.

Puede acceder a vínculos de retroceso en consultas utilizando la sintaxis @links.<ObjectType>.<PropertyName>, donde <ObjectType> y <PropertyName> hacen referencia a una propiedad específica en un tipo de objeto que hace referencia al tipo de objeto consultado.

// Find items that belong to a project with a quota greater than 10 (@links)
"@links.Project.items.quota > 10"

También puede definir una linkingObjects propiedad para incluir explícitamente el vínculo de retroceso en su modelo de datos. Esto le permite referenciarlo mediante un nombre de propiedad asignado utilizando la notación de punto estándar.

// Find items that belong to a project with a quota greater than 10 (LinkingObjects)
"projects.quota > 10"

El resultado de un vínculo de retroceso se trata como una colección y admite operadores de colección.

  // Find items where any project that references the item has a quota greater than 0
  "ANY @links.Project.items.quota > 0"
  // Find items where all projects that reference the item have a quota greater than 0
  "ALL @links.Project.items.quota > 0"

Puede utilizar operadores agregados en la colección de vínculos de retroceso.

  // Find items that are referenced by multiple projects
  "projects.@count > 1"
  // Find items that are not referenced by any project
  "@links.Project.items.@count == 0"
  // Find items that belong to a project where the average item has
  // been worked on for at least 5 minutes
  "@links.Project.items.items.@avg.progressMinutes > 10"

Puede consultar el recuento de todas las relaciones que apuntan a un objeto utilizando el operador @count directamente en @links.

// Find items that are not referenced by another object of any type
"@links.@count == 0"

Subconsultas

Iterar a través de las propiedades de la lista con otra consulta utilizando la función de predicado SUBQUERY().

Las subconsultas son útiles para los siguientes escenarios:

Coincidencia de cada objeto en una propiedad de lista en múltiples condiciones
Contar el número de objetos que coinciden con una subconsulta

SUBQUERY() tiene la siguiente estructura:

SUBQUERY(<collection>, <variableName>, <predicate>)

collection:El nombre de la propiedad a recorrer
variableName:Un nombre de variable del elemento a utilizar en la subconsulta
predicate: El predicado de subconsulta. Utiliza la variable especificada por variableName para referirse al elemento que se está iterando actualmente.

Una subconsulta itera a través de la colección dada y compara el predicado dado con cada objeto de la colección. El predicado puede hacer referencia al objeto iterado actual con el nombre de la variable pasado a SUBQUERY().

Una expresión de subconsulta se resuelve en una lista de objetos. Realm solo admite el operador de agregación @count en el resultado de una subconsulta. Esto permite contar cuántos objetos de la colección de entrada de la subconsulta coinciden con el predicado.

Puedes usar el conteo del resultado de la subconsulta como cualquier otro número en una expresión válida. En particular, puedes comparar el conteo con el número 0 para devolver todos los objetos coincidentes.

Ejemplo

El siguiente ejemplo muestra dos filtros de subconsulta en una colección de proyectos.

  // Returns projects with items that have not been completed
  // by a user named Alex.
  "SUBQUERY(items, $item, $item.isComplete == false AND $item.assignee == 'Alex').@count > 0"
  // Returns the projects where the number of completed items is
  // greater than or equal to the value of a project's `quota` property.
  "SUBQUERY(items, $item, $item.isComplete == true).@count >= quota"

Ordenar, distinguir y limitar

Ordene y limite la recopilación de resultados de su consulta utilizando operadores adicionales.

Operador	Descripción
`SORT`	Especifique el nombre de la propiedad que se va a comparar y si desea ordenar en orden ascendente (`ASC`) o descendente (`DESC`). Si especifica varios campos SORT, debe especificar el orden de cada uno. Con varios campos de ordenación, la consulta ordena por el primer campo y luego por el segundo. Por ejemplo, si `SORT (priority DESC, name DESC)`, la consulta devuelve el valor ordenado por prioridad y luego por nombre cuando el valor de prioridad es el mismo.
`DISTINCT`	Especifique el nombre de la propiedad que se va a comparar. Elimine los duplicados de esa propiedad en la colección de resultados. Si especifica varios campos DISTINCT, la consulta elimina los duplicados del primer campo y luego del segundo. Por ejemplo, si especifica `DISTINCT (name, assignee)`, la consulta solo elimina los duplicados con valores iguales en ambas propiedades.
`LIMIT`	Limite la recopilación de resultados al número especificado.

Ejemplo

Utilice los operadores de ordenación, distinción y límite del motor de consulta para encontrar elementos de tareas pendientes donde el asignado es Ali:

Ordenado por prioridad en orden descendente
Hacer cumplir la unicidad por nombre
Limitar los resultados a 5 elementos

"assignee == 'Ali' SORT(priority DESC) DISTINCT(name) LIMIT(5)"

Limitaciones de RQL de sincronización flexible

Requisitos de suscripción a campos consultables indexados

Añadir un campo consultable indexado a tu aplicación puede mejorar el rendimiento de consultas simples sobre datos con particiones estrictas. Por ejemplo, una aplicación donde las consultas asignan datos de forma estricta a un dispositivo, tienda o usuario,user_id == $0, “641374b03725038381d2e1fb” como, es una buena candidata para un campo consultable indexado. Sin embargo, un campo consultable indexado tiene requisitos específicos para su uso en una suscripción de consultas:

El campo consultable indexado debe usarse en todas las consultas de suscripción. No puede faltar en la consulta.
El campo consultable indexado debe usar una comparación == o IN con una constante al menos una vez en la consulta de suscripción. Por ejemplo, user_id == $0, "641374b03725038381d2e1fb" o store_id IN $0, {1,2,3}.

Opcionalmente, puede incluir una comparación AND siempre que el campo consultable indexado se compare directamente con una constante usando == o IN al menos una vez. Por ejemplo, store_id IN {1,2,3} AND region=="Northeast" o store_id == 1 AND (active_promotions < 5 OR num_employees < 10).

Las consultas de sincronización flexibleno válidas en un campo consultable indexado incluyen consultas donde:

El campo consultable indexado no usa AND con el resto de la consulta. Por ejemplo, store_id IN {1,2,3} OR region=="Northeast" no es válido porque usa OR en lugar de AND. De igual manera, store_id == 1 AND active_promotions < 5 OR num_employees < 10 no es válido porque AND solo se aplica al término contiguo, no a toda la consulta.
El campo consultable indexado no se utiliza en un operador de igualdad. Por ejemplo, store_id > 2 AND region=="Northeast" no es válido porque solo utiliza el operador > con el campo consultable indexado y no tiene una comparación de igualdad.
A la consulta le falta por completo el campo consultable indexado. Por ejemplo, region=="Northeast o truepredicate no son válidos porque no contienen dicho campo.

Operadores de consulta no admitidos en Flexible Sync

La sincronización flexible presenta algunas limitaciones al usar operadores RQL. Al escribir la suscripción de consulta que determina qué datos sincronizar, el servidor no admite estos operadores. Sin embargo, aún puede usar todas las funciones de RQL para consultar el conjunto de datos sincronizados en la aplicación cliente.

Tipo de operador	Operadores no compatibles
Operadores agregados	`@avg`, `@count`, `@max`, `@min`, `@sum`
Sufijos de consulta	`DISTINCT`, `SORT`, `LIMIT`

Las consultas que no distinguen entre mayúsculas y minúsculas ([c]) no pueden usar índices eficazmente. Por lo tanto, no se recomiendan, ya que podrían causar problemas de rendimiento.

Flexible Sync solo admite @count para campos de matriz.

Consultas de lista

Flexible Sync admite la consulta de listas mediante el operador IN.

Puede consultar una lista de constantes para ver si contiene el valor de un campo consultable:

// Query a constant list for a queryable field value
"priority IN { 1, 2, 3 }"

Si un campo consultable tiene un valor de matriz, puedes consultar para ver si contiene un valor constante:

// Query an array-valued queryable field for a constant value
"'comedy' IN genres"

Advertencia

No se pueden comparar dos listas en una consulta de sincronización flexible. Tenga en cuenta que esta sintaxis del lenguaje de consulta de dominio es válida fuera de las consultas de sincronización flexible.

// Invalid Flexible Sync query. Do not do this!
"{'comedy', 'horror', 'suspense'} IN genres"
// Another invalid Flexible Sync query. Do not do this!
"ANY {'comedy', 'horror', 'suspense'} != ANY genres"

Objetos incrustados o vinculados

La sincronización flexible no admite consultas sobre propiedades en objetos incrustados ni enlaces. Por ejemplo, obj1.field == "foo".

Límite de tamaño de consulta

El límite de tamaño para cualquier suscripción de consulta en su conjunto de suscripciones es de kB. Superar este límite genera 256 un error "LimitsExceeded".

Volver

Modificar esquema

Proyectos de ejemplo