Realm Query Language

Query com Realm SDKs

Para obter mais informações sobre métodos específicos de SDK para consulta de Realms, consulte a documentação de seu SDK:

Você também pode usar o Realm Query Language para procurar dados no Realm Studio. O Realm Studio é uma ferramenta visual para visualizar, editar e projetar arquivos do Realm.

Exemplos nesta página

Muitos dos exemplos nesta página usam um conjunto de dados simples para um aplicativo de lista de tarefas. Os dois tipos de objetos do Realm são Project e Item.

• Uma Item tem um nome, o nome do responsável e um sinalizador finalizado. Há também um número arbitrário de prioridade (maior é mais importante) e um número de minutos gastos trabalhando nisso.

• Um Project tem zero ou mais Items e uma cota opcional para o número mínimo de itens de tarefas esperado para ser concluído.

Consulte o esquema para estas duas classes, Project e Item, abaixo:

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;
}

Expressões

Os filtros consistem em expressões em um predicado. Uma expressão é uma das seguintes opções:

• O nome de uma propriedade do objeto que está sendo avaliados.

• Um operador e até duas expressões de argumento. Por exemplo, na expressão A + B, a totalidade de A + B é uma expressão, mas A e B também são expressões de argumento para o operador +.

• Um valor, como uma string ('hello') ou um número (5).

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

Queries parametrizadas

Crie queries parametrizadas para interpolar variáveis em instruções preparadas do Realm Query Language. A sintaxe das variáveis interpoladas é $<int>, começando em 0. Passe os argumentos posicionais como argumentos adicionais para os métodos do Realm SDK que usam a Realm Query Language.

Inclua apenas um parâmetro com $0.

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

Inclua vários parâmetros com números inteiros ascendentes, começando em $0.

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

Notação de ponto

Quando fizer referência a uma propriedade de objeto, você pode usar a notação de ponto para se referir a propriedades derivadas desse objeto. Você pode fazer referência até mesmo a propriedades de objetos embarcados e relacionamentos com a notação de pontos.

Por exemplo, considere uma query um objeto com uma propriedade workplace que se refere a um objeto de local de trabalho. O objeto do local de trabalho tem uma propriedade de objeto embarcado, address. Você pode encadear notação de ponto para se referir à propriedade de código postal desse endereço:

"workplace.address.zipcode == 10019"

Tipo de nil

O Realm Query Language inclui o tipo nil para representar um ponteiro nulo. Você pode referenciar nil diretamente em suas queries ou com uma query parametrizada. Se você estiver utilizando uma query parametrizada, cada SDK mapeará seu respectivo ponteiro nulo para nil.

"assignee == nil"

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

Operadores de comparação

A operação mais direta em uma pesquisa é a comparação de valores.

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

  // 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

Faça predicados compostos usando operadores lógicos.

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

Operadores de strings

Compare valores de string usando esses operadores de string. Os curingas do tipo Regex permitem mais flexibilidade na procurar.

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

Operadores ObjectId e UUID

Query ObjectIds e UUIDs BSON . Esses tipos de dados são frequentemente usados como chaves primárias.

Para fazer query com ObjectIds, use uma query parametrizada. Passe o ObjectId ou UUID em que você está fazendo uma query como argumento.

"_id == $0", oidValue

Você também pode colocar uma representação de string do ObjectId que você está avaliando no oid(<ObjectId String>).

"_id == oid(6001c033600510df3bbfd864)"

Para fazer uma query com UUIDs, coloque uma representação de string do UUID que você está avaliando no uuid(<UUID String>).

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

Operadores aritméticos

Realizar aritmética básica em um lado de uma expressão RQL ao avaliar tipos de dados numéricos.

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

Você também pode usar múltiplas propriedades de objeto juntas em uma operação matemática.

"progressMinutes * priority == 90"

Tipo de operador

Verifique o tipo de propriedade utilizando o operador @type. Você só pode usar o operador de tipo com tipos e dicionários mistos.

Avalie a propriedade em relação a uma representação de string do nome do tipo de dados. Consulte a documentação do SDK sobre o mapeamento dos tipos de dados da linguagem SDK para os tipos de dados do Realm.

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

Operadores de dicionário

Compare os valores do dicionário usando estes operadores de dicionário.

Você também pode usar operadores de dicionário em combinação com operadores de comparação para filtrar objetos com base em chaves e valores de dicionário. Os exemplos a seguir mostram algumas maneiras de usar operadores de dicionário com operadores de comparação. Todos os exemplos fazem query em uma coleção de objetos Realm com uma propriedade de dicionário denominada dict.

  // 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 datas

Faça query sobre tipos de data em um domínio.

Geralmente, você deve usar uma query parametrizada para passar um tipo de dados de data da linguagem do SDK que você está usando para uma query.

"timeCompleted < $0", someDate

Você também pode especificar datas das seguintes duas maneiras:

• Como uma data específica (em UTC)- YYYY-MM-DD@HH:mm:ss:nnnnnnnnnn (ano-mês-dia@horas:minutos:segundos:nanossegundos), UTC. Você também pode utilizar T em vez de @ para separar a data da hora.

• Como um tempo em segundos desde a época doUnix - Ts:n, onde T designa o início do tempo, s é o número de segundos e n é o número de nanossegundos.

A data é compatível com operadores de comparação.

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

Operadores agregados

Aplique um operador agregado a uma propriedade de coleção de um objeto de Realm. Operadores de agregação percorrem uma coleção e a reduzem para um único valor.

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 collections

Um operador de collection permite que você realize uma query das propriedades da lista dentro de uma collection de objetos. Os operadores de collection filtram uma collection aplicando um predicado a cada elemento de uma determinada propriedade de lista do objeto. Se o predicado retornar verdadeiro, o objeto será incluído na collection de saída.

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

Listar comparações

Você pode usar operadores de comparação e operadores de coleção para filtrar com base em listas de dados.

Você pode comparar qualquer tipo de lista válida. Isso inclui:

• coleção de Objeto de Realm, que permitem filter outros data no Realm.

  "oid(631a072f75120729dc9223d9) IN items.id"

• definidas diretamente na query, que permitem filtrar dados estáticos. Você define listas estáticas como uma lista separada por vírgulas de valores literais entre chaves de abertura ({) e fechamento (}).

  "priority IN {0, 1, 2}"

• objetos de lista nativos passados em uma expressão parametrizada, o que permite que você passe dados do aplicativo diretamente para suas queries.

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

Se você não definir um operador de coleção, uma expressão de lista padronizará para o operador ANY.

A tabela a seguir inclui exemplos que ilustram como os operadores de coleção interagem com listas e operadores de comparação:

Busca de texto completo

Você pode usar o RQL para consultar propriedades que tenham uma anotação de Full Text Search (FTS). O FTS suporta pesquisas booleanas de palavras correspondentes, em vez de pesquisas por relevância. Para obter informações sobre como habilitar o FTS em uma propriedade, consulte a documentação do FTS para seu SDK:

• SDK do Flutter

• SDK Kotlin

• SDK do .NET

• Node.js SDK

• React Native SDK

• O Swift SDK ainda não oferece suporte à Full Text Search.

Para consultar essas propriedades, use o predicado TEXT em sua consulta.

Você pode pesquisar palavras ou frases inteiras, ou limitar seus resultados com os seguintes caracteres:

• Exclua os resultados de uma palavra colocando o caractere - na frente da palavra.

• Especifique prefixos colocando o caractere * no final de um prefixo. Atualmente, a pesquisa por sufixo não é possível.

No exemplo seguinte, executamos a consulta do campo 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*"

Consultas geoespaciais

Você pode fazer query nos dados geoespaciais utilizando o operador geoWithin . O operador geoWithin usa o par latitude/longitude na propriedade coordinates de um objeto incorporado personalizado e uma forma geoespacial. O operador verifica se o ponto cordinates está contido dentro da forma geoespacial.

As seguintes formas geoespaciais são suportadas para query:

• GeoCircle

• GeoBox

• GeoPolygon

Para fazer query de dados geoespaciais:

1. Crie um objeto com uma propriedade contendo os dados geoespaciais incorporados.

2. Definir a forma geoespacial para configurar o limite da query.

3. Fazer consulta usando o operador geoWithin RQL.

Na query a seguir, verificamos se as coordenadas da propriedade location incorporada estão contidas na forma GeoCircle , smallCircle:

"location geoWithin $0", smallCircle

Para mais informações sobre definir formas e objetos geoespaciais com dados geoespaciais incorporados, consulte a documentação geoespacial para seu SDK:

• SDK do Flutter

• SDK Kotlin

• SDK do .NET

• Node.js SDK

• React Native SDK

• Swift SDK

Queries de backlink

Um backlink é um link de relacionamento inverso que permite pesquisar objetos que fazem referência a outro objeto. Os backlinks usam as relações to-one e to-many definidas em seus esquemas de objetos, mas revertem a direção. Cada relacionamento que você define em seu esquema tem implicitamente um backlink correspondente.

Você pode acessar backlinks em queries utilizando a sintaxe @links.<ObjectType>.<PropertyName>, onde <ObjectType> e <PropertyName> referem-se a uma propriedade específica em um tipo de objeto que referencia o tipo de objeto da query.

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

Você também pode definir uma propriedade linkingObjects para incluir explicitamente o backlink em seu modelo de dados. Isso permite que você faça referência ao backlink por meio de um nome de propriedade atribuído usando a notação de ponto padrão.

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

O resultado de um backlink é tratado como uma coleção e suporta operadores de coleção.

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

Você pode usar operadores agregados na coleção de backlink.

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

Você pode fazer a query na contagem de todos os relacionamentos que apontam para um objeto usando o operador @count diretamente em @links.

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

Subqueries

Iterar através das propriedades da lista com outra query utilizando a função de predicado SUBQUERY() .

As subqueries são úteis para os seguintes cenários:

• Correspondendo a cada objeto em uma propriedade de lista em várias condições

• Contando o número de objetos que correspondem a uma subquery

SUBQUERY() tem a seguinte estrutura:

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

• collection: o nome da propriedade pela qual fazer a iteração

• variableName: um nome de variável do elemento a ser usado na subquery

• predicate: O predicado da subquery. Use a variável especificada por variableName para se referir ao elemento atualmente iterado.

Uma subquery itera através da coleção fornecida e verifica o predicado fornecido em relação a cada objeto na coleção. O predicado pode se referir ao objeto iterado atual com o nome da variável passado para SUBQUERY().

Uma expressão de subquery resolve uma lista de objetos. O Realm suporta apenas o operador agregado @count no resultado de uma subquery. Isso permite que você conte quantos objetos na coleção de entrada da subquery correspondem ao predicado.

Você pode utilizar a contagem do resultado da subquery como qualquer outro número em uma expressão válida. Especificamente, você pode comparar a contagem com o número 0 para retornar todos os objetos correspondentes.

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

Classificar, distinguir e limitar

Classifique e limite a coleção de resultados da sua query usando operadores adicionais.

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

Limitações do RQL de sincronização flexível

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

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

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