RQL

Realm SDK によるクエリ

Realm をクエリするための SDK 固有のメソッドの詳細については、 SDK のドキュメントを参照してください。

RQLを使用してRealm Studio内のデータを参照することもできます。 Realm Studio は、Realm ファイルを表示、編集、設計するためのビジュアル ツールです。

このページの例

このページの例の多くでは、ToDo リスト アプリに単純なデータセットを使用しています。 2 つの Realm オブジェクトタイプはProjectとItemです。

• Itemには、名前、割り当て者の名前、完了したフラグがあります。 また、優先順位（値が大きいほど重要）と、その作業に費やされた時間数もあります。

• Projectには 0 個以上のItemsと、完了が予想される ToDo 項目の最小数に対する任意の割り当てがあります。

これらの 2 つのクラス、 ProjectとItemのスキーマを以下で参照してください。

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

式

フィルターは、述語内の式で構成されます。 式は、次のいずれかで構成されます。

• 現在評価されているオブジェクトのプロパティの名前。

• 演算子と最大 2 つの引数式（s）。 たとえば、式A + Bでは、 A + Bの全体が 式 ですが、 AとBは演算子+の引数式でもあります。

• string （'hello'）や数値（5）などの値。

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

パラメーター化されたクエリ

準備されたRQLステートメントに変数を挿入するためのパラメーター付きクエリを作成します。 補間変数の構文は$<int> から始まる0 です。Realmを使用する SDKRQL メソッドに、位置引数を追加の引数として渡します。

$0に 1 つのパラメータのみを含めます。

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

$0から始まる昇順の整数を持つ複数のパラメータを含めます。

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

ドット表記

オブジェクト プロパティを参照する場合、ドット表記を使用してそのオブジェクトの子プロパティを参照できます。 ドット表記で埋め込みオブジェクトと関係のプロパティを参照することもできます。

たとえば、ワークプレイス オブジェクトを参照するworkplaceプロパティを持つオブジェクトに対するクエリを考えてみましょう。 ワークプレイス オブジェクトには、埋め込みオブジェクト プロパティaddressがあります。 ドット表記を連鎖させて、その住所の郵便番号プロパティを参照できます。

"workplace.address.zipcode == 10019"

nil 型

RQLには、null ポインターを表す nil 型が含まれます。 nilは、クエリで直接参照することも、パラメータ化されたクエリを使用して参照することもできます。 パラメータ化されたクエリを使用している場合、各 SDK はそれぞれの null ポインターをnilにマッピングします。

"assignee == nil"

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

比較演算子

検索の最も簡単な操作は、値を比較することです。

"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

論理演算子

論理演算子を使用して複合述語を作成します。

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

string演算子

これらの string 演算子を使用して string 値を比較します。 正規表現のようなワイルドカードを使用すると、検索の柔軟性が向上します。

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

ObjectId 演算子と UUID 演算子

BSON ObjectIdとUUIDをクエリします。 これらのデータ型は、プライマリキーとしてよく使用されます。

ObjectId を使用してクエリを実行するには、 パラメーター化されたクエリ を使用します。 クエリ対象の ObjectId または UUID を引数として渡します。

"_id == $0", oidValue

また、評価対象の ObjectId の string 表現をoid(<ObjectId String>)に配置することもできます。

"_id == oid(6001c033600510df3bbfd864)"

UUID を使用してクエリするには、評価する UUID のstring表現を uuid(<UUID String>) に配置します。

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

算術演算子

数値データ型を評価するときに、RQL 式の一方の側で基本的な算術演算を実行します。

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

数学操作で複数のオブジェクト プロパティを一緒に使用することもできます。

"progressMinutes * priority == 90"

型演算子

@type演算子を使用してプロパティの型を確認します。 型演算子は、型と辞書が混在する場合のみ使用できます。

データ型名の string 表現に対してプロパティを評価します。 SDK 言語のデータ型から Realm データ型へのマッピングについては、SDK ドキュメントを参照してください。

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

辞書演算子

これらの辞書演算子を使用して、辞書値を比較します。

また、辞書演算子を比較演算子と組み合わせて使用し、辞書キーと値に基づいてオブジェクトをフィルタリングすることもできます。 次の例は、比較演算子とともに辞書演算子を使用する方法の一部を示しています。 すべての例では、 dictという名前の辞書プロパティを持つ Realm オブジェクトのコレクションがクエリされます。

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

日付演算子

Realm 内の日付型をクエリします。

一般的に、使用している SDK 言語からクエリに日付データ型を渡すには、パラメーター化されたクエリを使用する必要があります。

"timeCompleted < $0", someDate

次の 2 つの方法で日付を指定することもできます。

• 特定の日付として（UTC）- YYYY-MM-DD@HH:mm:ss:nnnnnnnnnn （year-month-day@hours:minutes:nanoseconds）、UTC 日付と時刻を区別するために、 @の代わりにTを使用することもできます。

• UNIX エポック からの時間（秒単位） - Ts:n（T は時間の開始を指定）、s は秒数、n はナノ秒数。

Date は比較演算子をサポートします。

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

集計演算子

Realm オブジェクトのコレクション プロパティに集計演算子を適用します。 集計演算子はコレクションを走査して、単一の値に縮小します。

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

コレクション 演算子

コレクション演算子を使用すると、オブジェクトのコレクション内のリスト プロパティをクエリできます。 コレクション演算子は、オブジェクトの特定のリスト プロパティのすべての要素に述語を適用してコレクションをフィルタリングします。 述語が true を返す場合、オブジェクトは出力コレクションに含まれます。

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

リストの比較

比較演算子とコレクション演算子を使用して、データのリストに基づいてフィルタリングできます。

任意のタイプの有効なリストを比較できます。 これには以下が含まれます。

• Realm オブジェクトのコレクション。Realm 内の他のデータをフィルタリングできます。

  "oid(631a072f75120729dc9223d9) IN items.id"

• はクエリで直接定義されるリストを表示し、静的データをフィルタリングできます。 静的リストは、開始括弧（ { ）と閉じ括弧（ } ）で囲まれたリテラル値のカンマ区切りリストとして定義します。

  "priority IN {0, 1, 2}"

• パラメータ化された式で渡されるネイティブ リスト オブジェクト。これにより、アプリケーション データをクエリに直接渡すことができます。

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

コレクション演算子を定義しない場合、リスト式はデフォルトでANY演算子になります。

次の表には、コレクション演算子がリストおよび比較演算子とどのように相互作用するのかを示す例えが含まれています。

全文検索

RQL を使用して、全文検索（FTS）注釈を持つプロパティをクエリできます。 FTS は関連性の検索ではなく、ブール値一致の単語検索をサポートしています。 プロパティで FTS を有効にする方法の詳細については、SDK の FTS ドキュメントを参照してください。

• Flutter SDK

• Kotlin SDK

• .NET SDK

• Node.js SDK

• React Native SDK

• Swift SDK はまだ全文検索をサポートしていません。

これらのプロパティをクエリするには、クエリでTEXT述語を使用します。

単語またはフレーズ全体を検索したり、次の文字で結果を制限したりすることもできます。

• 単語の前に-文字を付けて、単語の結果を除外します。

• プレフィックスの末尾に*文字を配置してプレフィックスを指定します。 サフィックス検索は現在サポートされていません。

次の例では、 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*"

地理空間クエリ

geoWithin演算子を使用して、地理空間データに対してクエリを実行できます。 geoWithin演算子は、カスタム埋め込みオブジェクトのcoordinatesプロパティと地理空間形状の緯度と経度のペアを受け取ります。 演算子は、 cordinates点が地理空間形状内に含まれているかどうかを確認します。

次の地理空間の形状はクエリでサポートされています。

• GeoCircle

• GeoBox

• GeoPolygon

地理空間データをクエリするには、次のようにします。

1. 埋め込み地理空間データを含む プロパティを持つオブジェクトを作成します。

2. 地理空間の形状を定義して、クエリの境界を設定します。

3. geoWithin RQL 演算子を使用してクエリを実行します。

次のクエリでは、埋め込みlocationプロパティの座標がGeoCircleの形状、 smallCircle内に含まれていることを確認しています。

"location geoWithin $0", smallCircle

地理空間シェイプと地理空間データが埋め込まれたオブジェクトの定義の詳細については、SDK の地理空間ドキュメントを参照してください。

• Flutter SDK

• Kotlin SDK

• .NET SDK

• Node.js SDK

• React Native SDK

• Swift SDK

バックリンク クエリ

バックリンクは、別のオブジェクトを参照するオブジェクトを検索できる逆関係リンクです。 バックリンクは、オブジェクト スキーマで定義されている 1 対多の関係を使用しますが、方向は逆です。 スキーマで定義するすべての関係には、対応するバックリンクが暗黙的にあります。

@links.<ObjectType>.<PropertyName>構文を使用してクエリでバックリンクにアクセスできます。 <ObjectType>と<PropertyName>は、クエリされたオブジェクトタイプを参照するオブジェクトタイプ上の特定のプロパティを参照します。

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

また、 linkingObjectsプロパティを定義して、データモデルにバックリンクを明示的に含めることもできます。 こうすると、標準のドット表記を使用して、割り当てられたプロパティ名を介してバックリンクを参照できるようになります。

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

バックリンクの結果はコレクションのように扱われ、コレクション演算子をサポートします。

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

バックリンク コレクションでは集計演算子を使用できます。

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

オブジェクトを指しているすべての関係の数をクエリするには、 @count演算子を@linksで直接使用します。

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

サブクエリ

SUBQUERY()述語関数を使用して、別のクエリでリスト プロパティを反復処理します。

サブクエリは、次のシナリオで役立ちます。

• 複数の条件でのリスト プロパティ内の各オブジェクトの一致

• サブクエリに一致するオブジェクト数のカウント

SUBQUERY() の構造は次のとおりです。

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

• collection: 反復処理するプロパティの名前

• variableName: サブクエリで使用する要素の変数名

• predicate: サブクエリ述語。 現在反復処理されている要素を参照するには、 variableNameで指定された変数を使用します。

サブクエリは指定されたコレクションを反復処理し、指定された述語をコレクション内の各オブジェクトと照合します。 述語は、 SUBQUERY()に渡された変数名を持つ現在の反復オブジェクトを参照できます。

サブクエリ式は、オブジェクトのリストに変換されます。 Realm では、サブクエリの結果に対してのみ@count集計演算子をサポートします。 これにより、述語に一致したサブクエリ入力コレクション内のオブジェクトの数をカウントできます。

サブクエリ結果のカウントは、有効な 式 内の他の数値と同様に使用できます。 特に、カウントと数値0を比較すると、一致するすべてのオブジェクトを返すことができます。

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

ソート、個別、制限

追加の演算子を使用して、クエリの結果コレクションをソートして制限します。

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

Flexible Sync RQL の制限

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