managed 동기화 구독 - Node.js SDK

쿼리 구독

구독에 이름을 지정하는 것이 좋습니다. 이렇게 하면 구독을 더 쉽게 찾고 관리할 수 있습니다. 구독 이름은 고유해야 합니다. 기존 구독과 동일한 이름으로 구독을 추가하려고 하면 오류가 발생합니다.

쿼리를 구독하려면 다음과 같이 하세요:

1. 읽고 쓰고자 하는 객체를 쿼리합니다.

2. 쿼리 결과에서 subscribe() 를 호출하여 쿼리와 일치하는 객체에 대한 동기화 구독을 만듭니다.

3. SubscriptionOptions객체에 name 속성을 포함시켜 subscribe() 함수에 전달합니다.

const subOptions = {
  name: "All completed tasks",
};
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe(subOptions);
const completedTasksSubscription = realm.subscriptions.findByName(
  "All completed tasks"
);
// ...work with the subscribed results list or modify the subscription

const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe({ name: "All completed tasks" });
const completedTasksSubscription = realm.subscriptions.findByName(
  "All completed tasks"
);
// ...work with the subscribed results list or modify the subscription

구독 이름 없이 쿼리 구독하기

대부분의 경우 구독에 이름을 지정해야 합니다. 그렇지 않으면 이름은 null로 설정됩니다.

이름이 지정되지 않은 쿼리 구독에 filtered() 를 사용하는 경우 구독 식별자는 filtered 쿼리를 기반으로 합니다. 이는 쿼리 문자열이 변경될 때마다 subscribe()가 새 구독을 생성한다는 의미입니다.

const config = {
  schema: [Task],
  sync: {
    user: app.currentUser,
    flexible: true,
  },
};
const realm = await Realm.open(config);
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe();
// ...work with the subscribed results list

const config: Realm.Configuration = {
  schema: [Task],
  sync: {
    user: app.currentUser!,
    flexible: true,
  },
};
const realm = await Realm.open(config);
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe();
// ...work with the subscribed results list

쿼리 구독이 동기화될 때까지 기다리기

쿼리 결과를 구독하는 경우 동기화된 데이터가 다운로드될 때까지 결과에는 객체가 포함되지 않습니다. 동기화된 객체의 다운로드가 완료될 때까지 기다려야 하는 경우 waitForSync 을 사용합니다. 구독에 대한 다양한 동작과 다운로드 위팅을 처리하는 방법을 지정할 수 있습니다.

이 예시에서는 기본 동작인 FirstTime 옵션을 사용합니다. FirstTime 동작이 있는 구독은 구독이 처음 생성될 때 동기화가 완료될 때까지만 기다립니다.

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Only waits for sync to finish on the initial sync.
await completedTasks.subscribe({
  behavior: WaitForSync.FirstTime,
  name: "First time sync only",
});

지원되는 다른 WaitForSync 옵션은 다음과 같습니다.

• Always: 앱이 실행될 때마다 일치하는 객체를 다운로드할 때까지 기다립니다. 앱을 실행할 때마다 인터넷에 연결되어 있어야 합니다.

• Never: 일치하는 객체를 다운로드하기 위해 기다리지 마세요. 앱을 처음 실행할 때는 사용자가 인증하기 위해 인터넷 연결이 필요하지만, 이후 실행 시 캐시된 자격 증명을 사용하여 오프라인으로 열 수 있습니다.

선택적으로 timeout 값을 지정하여 동기화 다운로드가 실행되는 시간을 제한할 수 있습니다.

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Add subscription with timeout
// If timeout expires before sync is completed, currently-downloaded
// objects are returned and sync download continues in the background.
const taskSubscription = await completedTasks.subscribe({
  behavior: WaitForSync.Always,
  timeout: 500,
});

쿼리 구독 취소

unsubscribe() 을(를) 사용하여 쿼리 결과의 구독을 취소할 수 있습니다.

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Only waits for sync to finish on the initial sync.
await completedTasks.subscribe({
  behavior: WaitForSync.FirstTime,
  name: "First time sync only",
});
// Unsubscribe
completedTasks.unsubscribe();

이렇게 하면 수동으로 구독을 제거하는 것과 유사하게 활성 구독 목록에서 구독이 제거됩니다.

겹치는 객체가 포함된 다른 구독이 있는 경우 unsubscribe()을(를) 호출한 후에도 결과 목록에 여전히 객체가 포함될 수 있습니다.

unsubscribe()을(를) 호출하면 연결된 구독이 제거됩니다. 구독은 이름으로 제거됩니다. 이름이 없으면 unsubscribe()은(는) unsubscribe()을(를) 호출한 쿼리와 정확히 일치하는 쿼리를 모두 제거합니다.

제거된 구독과 일치하는 객체가 영역에서 삭제되기 전에 unsubscribe() 메서드가 반환됩니다. 동기화는 새 구독 세트를 기반으로 백그라운드에서 계속됩니다.

모든 구독 가져오기

유연한 동기화 Realm을 사용하는 경우 realm.subscriptions 메서드 를 통해 구독 컬렉션 SubscriptionSet 에 액세스할 수 있습니다. 속성.

// get the SubscriptionSet for the realm
const subscriptions = realm.subscriptions;

구독 추가

구독은 영역 쿼리의 결과를 기반으로 합니다.

다음 예시에서는 completed 및 progressMinutes이(가) App Services App에서 쿼리 가능한 필드로 설정되어 있습니다. 클라이언트 코드에서 필터링된 쿼리를 생성한 다음 그 결과를 구독합니다.

• 완료된 작업

• 120 이상 걸린 완료된 작업 progressMinutes

const tasks = realm.objects("Task");
const longRunningTasks = tasks.filtered(
  'status == "completed" && progressMinutes > 120'
);
await realm.subscriptions.update((mutableSubs) => {
  mutableSubs.add(longRunningTasks, {
    name: "longRunningTasksSubscription",
  });
  mutableSubs.add(realm.objects("Team"), {
    name: "teamsSubscription",
  });
});

초기 구독 설정

Flexible Sync 영역에서 읽거나 쓰려면 먼저 구독이 하나 이상 있어야 합니다. 영역을 열 때 초기 구독을 추가할 수 있습니다.

초기 구독을 설정하려면 Realm의 SyncConfiguration 에 initialSubscriptions 필드를 포함하세요. initialSubscriptions 객체 내에서 쿼리를 구독하는 콜백에 update 필드 세트를 추가합니다.

const config = {
  schema: [Task],
  sync: {
    user: app.currentUser,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(realm.objects(Task).filtered("status == 'in progress'"), {
          name: "In progress tasks",
        });
      },
      rerunOnOpen: true,
    },
  },
};
const realm = await Realm.open(config);

const config: Realm.Configuration = {
  schema: [Task],
  sync: {
    user: app.currentUser!,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(realm.objects(Task).filtered("status == 'in progress'"), {
          name: "In progress tasks",
        });
      },
      rerunOnOpen: true,
    },
  },
};
const realm = await Realm.open(config);

기본적으로 초기 구독은 영역이 처음 열릴 때만 생성됩니다. 앱이 시작될 때마다 이 초기 구독을 다시 실행해야 하는 경우 rerunOnOpen을(를) true(으)로 설정할 수 있습니다. 동적 시간 범위 또는 구독에 대한 정적 변수를 다시 계산해야 하는 기타 쿼리를 다시 실행하려면 이 작업을 수행해야 할 수 있습니다.

구독 상태 확인

구독 상태 를 확인하여 서버 가 구독 을 승인했는지, 장치가 로컬로 데이터를 다운로드했는지 확인할 수 있습니다.

구독 상태를 사용하여 다음을 수행할 수 있습니다.

• Trigger error handling

• 트랜잭션이 보류 중인지 또는 완료되었는지 표시

• 구독 세트 대체 시기를 확인하고 구독 변경 사항을 작성하려면 해당 구독 세트의 새 인스턴스를 가져와야 합니다

Node.js v12.0.0 구독 상태를 가져오는 데 사용할 수 있는 SubscriptionSetState 열거형 을 추가했습니다.

새 쿼리로 구독 업데이트하기

새 쿼리로 이름이 지정된 구독을 업데이트할 수 있습니다. 구독 쿼리를 업데이트하려면 업데이트하려는 구독 이름과 함께 새 쿼리와 구독 옵션을 MutableSubscriptionSet.add() 메서드에 전달합니다. 새 구독을 추가하는 것과 마찬가지로 subscriptions.update()를 호출하여 트랜잭션 내에서 구독을 업데이트해야 합니다.

다음 예에서는 장기 실행 작업을 180분 이상 소요된 모든 작업으로 재정의합니다.

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.add(
    tasks.filtered('status == "completed" && progressMinutes > 180'),
    {
      name: "longRunningTasksSubscription",
    }
  );
});

구독 제거

여러 가지 방법으로 구독을 제거할 수 있습니다.

• 특정 쿼리로 단일 구독 제거

• 특정 이름으로 단일 구독 제거

• 특정 객체 모델에 대한 모든 구독 제거

• 이름 없는 모든 구독 제거

• 모든 구독 삭제

구독 쿼리를 제거하면 서버는 클라이언트 장치에서 동기화된 데이터도 제거합니다.

realm.subscriptions.update((mutableSubs) => {
  // remove a subscription with a specific query
  mutableSubs.remove(tasks.filtered('owner == "Ben"'));
});

realm.subscriptions.update((mutableSubs) => {
  // remove a subscription with a specific name
  mutableSubs.removeByName("longRunningTasksSubscription");
});

let subscriptionReference;
realm.subscriptions.update((mutableSubs) => {
  subscriptionReference = mutableSubs.add(realm.objects("Task"));
});
// later..
realm.subscriptions.removeSubscription(subscriptionReference);

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeByObjectType("Team");
});

// Remove unnamed subscriptions.
let numberRemovedSubscriptions = 0;
await realm.subscriptions.update((mutableSubs) => {
  numberRemovedSubscriptions = mutableSubs.removeUnnamed();
});

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeAll();
});

API 효율성

쿼리 구독 섹션에 설명된 subscribe() 및 unsubscribe() API를 사용하여 여러 구독을 관리하는 것은 수동으로 구독을 관리할 때 배치 업데이트를 수행하는 것보다 효율성이 떨어집니다.

구독을 여러 번 변경할 때 성능을 향상하려면 subscriptions API를 사용하여 단일 트랜잭션으로 모든 구독을 업데이트합니다. 방법을 알아보려면 수동으로 구독 관리하기를 참조하세요.

성능 향상을 위한 그룹 업데이트

구독 세트에 대한 모든 쓰기 트랜잭션(write transaction)에는 성능이 소모됩니다. 세션 중에 영역 객체를 여러 번 업데이트해야 하는 경우 모든 변경이 완료될 때까지 편집한 객체를 메모리에 보관하는 것이 좋습니다. 이렇게 하면 모든 변경 사항 대신 완전하고 업데이트된 객체만 영역에 기록하므로 동기화 성능이 향상됩니다.

인덱싱된 쿼리 가능 필드 구독 요구 사항

앱에 인덱싱된 쿼리 가능 필드 를 추가하면 강력하게 분할된 데이터에 대한 간단한 쿼리의 성능을 향상시킬 수 있습니다. 예를 들어 user_id == $0, “641374b03725038381d2e1fb” 와 같이 쿼리가 데이터를 기기, 스토어 또는 사용자에 강력하게 매핑하는 앱은 인덱싱된 쿼리 가능 필드의 좋은 후보입니다. 그러나 인덱싱된 쿼리 가능 필드에는 쿼리 구독에 사용하기 위한 특정 요구 사항이 있습니다.

• 인덱싱된 쿼리 가능 필드는 모든 구독 쿼리에서 사용해야 합니다. 쿼리에서 누락되어서는 안 됩니다.

• 인덱싱된 쿼리 가능 필드는 구독 쿼리에서 상수에 대해 == 또는 IN 비교를 한 번 이상 사용해야 합니다. 예를 들어 user_id == $0, "641374b03725038381d2e1fb" 또는 store_id IN $0, {1,2,3}입니다.

인덱싱된 쿼리 가능 필드가 == 또는 IN을 사용하여 상수와 한 번 이상 직접 비교되는 경우, 선택적으로 AND 비교를 포함할 수 있습니다. 예를 들어 store_id IN {1,2,3} AND region=="Northeast" 또는 store_id == 1 AND (active_promotions < 5 OR num_employees < 10) 입니다.

인덱싱된 쿼리 가능 필드에 대한 유효하지 않은 Flexible Sync 쿼리에는 다음과 같은 쿼리가 포합됩니다.

• 인덱싱된 쿼리 가능 필드가 AND를 나머지 쿼리와 함께 사용하지 않는 경우.예를 들어 store_id IN {1,2,3} OR region=="Northeast"은 AND 대신 OR을 사용하므로 유효하지않습니다. 마찬가지로 store_id == 1 AND active_promotions < 5 OR num_employees < 10는 AND가 전체 쿼리가 아니라 옆에 있는 용어에만 적용되므로 유효하지 않습니다.

• 인덱싱된 쿼리 가능 필드가 동등 연산자에 사용되지 않는 경우.예를 들어 store_id > 2 AND region=="Northeast"는 > 연산자만 인덱싱된 쿼리 가능 필드에 사용하고 동등 비교는 없기 때문에 유효하지 않습니다.

• 인덱싱된 쿼리 가능 필드가 쿼리에서 완전히 누락된 경우.예를 들어region=="Northeast 또는 truepredicate는 인덱싱된 쿼리 가능 필드를 포함하지 않으므로 유효하지 않습니다.

Flexible Sync에서 지원되지 않는 쿼리 연산자

Flexible Sync는 RQL 연산자를 사용할 때 몇 가지 제한 사항이 있습니다. 동기화할 데이터를 결정하는 쿼리 구독 을 작성할 때 서버는 이러한 쿼리 연산자를 지원하지 않습니다. 그러나 전체 RQL 기능을 사용하여 클라이언트 애플리케이션에서 동기화된 데이터 세트를 쿼리할 수 있습니다.

대소문자를 구분하지 않는 쿼리([c])은(는) 인덱스를 효과적으로 사용할 수 없습니다. 대소문자를 구분하지 않는 쿼리는 성능 문제를 일으킬 수 있으므로 사용하지 않는 것이 좋습니다.

Flexible Sync는 배열 필드에 대해 @count만 지원합니다.

목록 쿼리

Flexible Sync는 IN 연산자를 사용하여 목록 쿼리를 지원합니다.

상수 목록을 쿼리하여 쿼리 가능 필드 값이 포함되어 있는지 확인할 수 있습니다:

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

임베디드 또는 링크된 객체

Flexible Sync는 내장된 객체 또는 링크의 속성에 대한 쿼리를 지원하지 않습니다. 예시: obj1.field == "foo"

쿼리 크기 제한

구독 설정하다 에 있는 특정 쿼리 구독 의 크기 제한 은 256 KB 입니다. 이 제한을 초과하면 LimitsExceeded 오류가 발생합니다.