Realm Query Language

Realm SDK를 이용한 쿼리

Realm 쿼리를 위한 SDK별 방법에 대한 자세한 내용은 SDK 설명서를 참조하세요.

Realm Query Language를 사용해서 Realm Studio에서 데이터를 검색할 수도 있습니다. Realm Studio는 Realm 파일의 조회, 편집, 설계를 할 수 있는 시각 도구입니다.

이 페이지의 예제

이 페이지의 여러 예제에서는 해야 할 일 목록 앱에 간단한 데이터 세트를 사용합니다. 두 가지 Realm 객체 유형은 Project 및 Item입니다.

• Item에는 이름, 담당자 이름, 완료 플래그가 있습니다. 우선 순위를 뜻하는 임의 숫자(클수록 중요도가 높음)와 작업 소요 시간(분)도 있습니다.

• Project은(는) 0 이상의 Items 값을 갖고 있으며, 완료될 것으로 예상되는 해야 할 일 항목의 최소 개수에 대한 선택적 할당량입니다.

아래에서 이 두 클래스의 스키마 Project 및 Item를 참조하세요.

표현식

필터는 조건자의 표현식으로 구성되어 있습니다. 표현식은 다음 중 한 가지로 구성되어 있습니다.

• 현재 평가 중인 객체의 속성 이름입니다.

• 연산자와 최대 2개의 인수 표현식입니다. 그 예로 A + B 표현식에서는 A + B 전체가 표현식이지만, A와(과) B도 연산자 +에 대한 인수 표현식입니다.

• 값으로는 문자열('hello') 또는 숫자(5) 등이 있습니다.

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

매개변수화된 쿼리

매개변수화된 쿼리를 생성해서 작성된 Realm Query Language 성명서에 변수를 보간하세요. 보간된 변수의 구문은 0(으)로 시작하는 $<int>입니다. Realm Query Language를 사용하는 Realm SDK 메서드에 위치 인수를 추가 인수로 전달하세요.

값이 $0인 매개변수를 1개만 포함시키세요.

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

$0(으)로 시작하는 오름차순 정수로 매개변수를 여러 개 포함시키세요.

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

점 표기법

객체 속성을 참조할 때는 점 표기법 을 사용하여 해당 객체의 하위 속성을 참조할 수 있습니다. 점 표기법을 사용하여 포함된 객체의 속성과 관계를 참조할 수도 있습니다.

그 예로 어떤 쿼리는 Workplace 객체를 참조하는 workplace 속성을 가진 객체를 대상으로 합니다. Workplace 객체에는 포함된 객체 속성인 address이(가) 있습니다. 해당 주소의 우편번호 속성을 참조하기 위해 점 표기법을 연결할 수 있습니다.

"workplace.address.zipcode == 10019"

Nil 유형

Realm Query Language에는 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

문자열 연산자

이러한 문자열 연산자를 사용하여 문자열 값을 비교합니다. 정규식과 유사한 와일드카드를 사용하면 더욱 유연하게 검색할 수 있습니다.

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

객체 ID 및 UUID 연산자

BSON ObjectId 및 UUID 를 쿼리합니다. 이러한 데이터 유형은 종종 프라이머리 키로 사용됩니다.

객체 ID로 쿼리하려면 매개 변수화된 쿼리를 사용하세요. 쿼리하려는 객체 ID 또는 UUID를 인수로 전달합니다.

"_id == $0", oidValue

평가하려는 객체 ID의 문자열 표현을 oid(<ObjectId String>)에 입력할 수도 있습니다.

"_id == oid(6001c033600510df3bbfd864)"

UUID로 쿼리하려면 평가하려는 UUID의 문자열 표현을 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 연산자를 사용하여 속성의 유형을 확인하세요. 이 유형 연산자는 유형과 사전이 혼합된 경우에만 사용할 수 있습니다.

데이터 유형 이름의 문자열 표현과 비교하여 속성을 평가합니다. 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

다음 두 가지 방법으로 날짜를 지정할 수도 있습니다.

• 특정 날짜(UTC)- YYYY-MM-DD@HH:mm:ss:nnnnnnnnnn (년-월-일@시간:분:초:나노초), UTC. @ T 을(를) 사용하여 날짜와 시간을 구분할 수도 있습니다.

• Unix epoch Ts:n T 이후의 시간(초) - , 여기서s 는 시간의 시작을 나타내고,n 는 초 수이며, 는 나노초 수입니다.

날짜는 비교 연산자를 지원합니다.

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 객체의 컬렉션을 사용하여 영역의 다른 데이터에 대해 필터링할 수 있습니다.

  "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을 사용하여 Full Text Search(FTS) 어노테이션이 있는 속성에 대해 쿼리할 수 있습니다. FTS는 관련성 검색보다는 부울 일치 단어 검색을 지원합니다. 속성에서 FTS를 활성화하는 방법에 대한 자세한 내용은 SDK에 대한 FTS 설명서를 참조하세요.

• Flutter SDK

• Kotlin SDK

• .NET SDK

• Node.Js SDK

• React Native SDK

• Swift SDK는 아직 Full Text Search를 지원하지 않습니다.

이러한 속성을 쿼리하려면 쿼리에 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

역링크 쿼리

역링크는 다른 객체를 참조하는 객체를 조회할 수 있는 역관계 링크입니다. 역링크는 객체 스키마에 정의된 일대일 및 다대다 관계를 사용하지만 방향은 반대입니다.스키마에서 정의하는 모든 관계에는 암시적으로 해당 역링크가 있습니다.

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

@links에 @count 연산자를 직접 사용하면 객체를 가리키는 모든 관계의 수를 쿼리할 수 있습니다.

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

유연한 동기화 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"