Class Realm

The Realm database.

Constructors

  • Create a new Realm instance, at the default path.

    Returns Realm

    Throws

    An Error when an incompatible synced Realm is opened.

  • Create a new Realm instance at the provided path.

    Parameters

    • path: string

      Required when first creating the Realm.

    Returns Realm

    Throws

    An Error if the Realm cannot be opened at the provided path.

    Throws

    An Error when an incompatible synced Realm is opened.

  • Create a new Realm instance using the provided config. If a Realm does not yet exist at config.path (or Realm.defaultPath if not provided), then this constructor will create it with the provided config.schema (which is required in this case). Otherwise, the instance will access the existing Realm from the file at that path. In this case, config.schema is optional or not have changed, unless config.schemaVersion is incremented, in which case the Realm will be automatically migrated to use the new schema. In the case of query-based sync, config.schema is required. An exception will be thrown if config.schema is not defined.

    Parameters

    Returns Realm

    Throws

    An Error if anything in the provided config is invalid.

    Throws

    An Error when an incompatible synced Realm is opened.

Properties

beforeNotifyListeners: any
changeListeners: any
classes: any
handleInitialSubscriptions: any

Update subscriptions with the initial subscriptions if needed.

Param: initialSubscriptions

The initial subscriptions.

Param: realmExists

Whether the realm already exists.

schemaExtras: any
schemaListeners: any
syncSession: null | Session

The sync session if this is a synced Realm

defaultPath: string
determineEncryptionKey: any
determinePath: any

Note

When the path is relative and the config contains a sync object, Core will replace any existing file extension or add the ".realm" suffix.

determineSchemaMode: any
extractSchemaExtras: any
internals: any
normalizePath: any

TODO: Consider breaking this by ensuring a ".realm" suffix (coordinating with other SDK teams in the process)

wrapMigration: any

Accessors

  • get isClosed(): boolean
  • Indicates if this Realm has been closed.

    Returns boolean

    true if closed, false otherwise.

    Since

    2.1.0

  • get isEmpty(): boolean
  • Indicates if this Realm contains any objects.

    Returns boolean

    true if empty, false otherwise.

    Since

    1.10.0

  • get isInMemory(): boolean
  • Indicates if this Realm was opened in-memory.

    Returns boolean

    true if this Realm is in-memory, false otherwise.

  • get isInMigration(): boolean
  • Indicates if this Realm is in migration.

    Returns boolean

    true if in migration, false otherwise

    Since

    12.3.0

  • get isInTransaction(): boolean
  • Indicates if this Realm is in a write transaction.

    Returns boolean

    true if in a write transaction, false otherwise.

    Since

    1.10.3

  • get isReadOnly(): boolean
  • Indicates if this Realm was opened as read-only.

    Returns boolean

    true if this Realm is read-only, false otherwise.

    Since

    0.12.0

  • get path(): string
  • The path to the file where this Realm is stored.

    Returns string

    A string containing the path to the file where this Realm is stored.

    Since

    0.12.0

  • get schemaVersion(): number
  • The current schema version of the Realm.

    Returns number

    The schema version of this Realm, as a number.

    Since

    0.12.0

  • get subscriptions(): SubscriptionSet
  • The latest set of flexible sync subscriptions.

    Returns SubscriptionSet

    A SubscriptionSet object.

    Throws

    An Error if flexible sync is not enabled for this app.

Methods

  • Type Parameters

    • T extends Object<DefaultObject, never, T>

    Parameters

    • type: Constructor<T>
    • objectKey: string

    Returns undefined | T

  • Add a listener callback for the specified eventName.

    Parameters

    • eventName: RealmEventName

      The name of event that should cause the callback to be called.

    • callback: RealmListenerCallback

      Function to be called when a change event occurs. Each callback will only be called once per event, regardless of the number of times it was added.

    Returns void

    Throws

    An Error if an invalid event eventName is supplied, if Realm is closed or if callback is not a function.

  • Initiate a write transaction.

    When doing a transaction, it is highly recommended to do error handling. If you don't handle errors, your data might become inconsistent. Error handling will often involve canceling the transaction.

    Returns void

    Throws

    An Error if already in write transaction

    See

    Example

    realm.beginTransaction();
    try {
    realm.create('Person', { name: 'Arthur Dent', origin: 'Earth' });
    realm.create('Person', { name: 'Ford Prefect', origin: 'Betelgeuse Five' });
    realm.commitTransaction();
    } catch (e) {
    realm.cancelTransaction();
    throw e;
    }
  • Cancel a write transaction.

    Returns void

  • Closes this Realm so it may be re-opened with a newer schema version. All objects and collections from this Realm are no longer valid after calling this method. The method is idempotent.

    Returns void

  • Commit a write transaction.

    Returns void

  • Replaces all string columns in this Realm with a string enumeration column and compacts the database file.

    Cannot be called from a write transaction.

    Compaction will not occur if other Realm instances exist.

    While compaction is in progress, attempts by other threads or processes to open the database will wait.

    Be warned that resource requirements for compaction is proportional to the amount of live data in the database. Compaction works by writing the database contents to a temporary database file and then replacing the database with the temporary one.

    Returns boolean

    true if compaction succeeds, false if not.

  • Create a new RealmObject of the given type and with the specified properties. For objects marked asymmetric, undefined is returned. The API for asymmetric objects is subject to changes in the future.

    Type Parameters

    • T = DefaultObject

    Parameters

    • type: string

      The type of Realm object to create.

    • values: Partial<T> | Partial<Unmanaged<T>>

      Property values for all required properties without a default value.

    • Optional mode: boolean | Never | Modified | All

      Optional update mode. The default is UpdateMode.Never.

    Returns Object<T, never> & T

    A RealmObject or undefined if the object is asymmetric.

  • Type Parameters

    Parameters

    Returns T

  • Deletes the provided Realm object, or each one inside the provided collection.

    Parameters

    • subject: any

      The Realm object to delete, or a collection containing multiple Realm objects to delete.

    Returns void

  • WARNING: This will delete all objects in the Realm!

    Returns void

  • Deletes a Realm model, including all of its objects. If called outside a migration function, schema and schemaVersion are updated.

    Parameters

    • name: string

      The model name.

    Returns void

  • Searches for a Realm object by its primary key.

    Type Parameters

    • T = DefaultObject

    Parameters

    • type: string

      The type of Realm object to search for.

    • primaryKey: T[keyof T]

      The primary key value of the object to search for.

    Returns null | Object<T, never> & T

    A RealmObject or null if no object is found.

    Throws

    An Error if type passed into this method is invalid, or if the object type did not have a primaryKey specified in the schema, or if it was marked asymmetric.

    Since

    0.14.0

  • Type Parameters

    Parameters

    • type: Constructor<T>
    • primaryKey: T[keyof T]

    Returns null | T

  • Returns all objects of the given type in the Realm.

    Type Parameters

    • T = DefaultObject

    Parameters

    • type: string

      The type of Realm objects to retrieve.

    Returns Results<Object<T, never> & T>

    Results that will live-update as objects are created, modified, and destroyed.

    Throws

    An Error if type passed into this method is invalid or if the type is marked embedded or asymmetric.

  • Type Parameters

    • T extends Object<any, never, T> = Object<DefaultObject, never> & DefaultObject

    Parameters

    • type: Constructor<T>

    Returns Results<T>

  • Remove all event listeners (restricted to the event eventName, if provided).

    Parameters

    • Optional eventName: RealmEventName

      The name of the event whose listeners should be removed.

    Returns void

    Throws

    An Error when invalid event eventName is supplied.

  • Remove the listener callback for the specified event eventName.

    Parameters

    Returns void

    Throws

    an Error If an invalid event eventName is supplied, if Realm is closed or if callback is not a function.

  • Synchronously call the provided callback inside a write transaction. If an exception happens inside a transaction, you’ll lose the changes in that transaction, but the Realm itself won’t be affected (or corrupted). More precisely, beginTransaction and commitTransaction will be called automatically. If any exception is thrown during the transaction cancelTransaction will be called instead of commitTransaction and the exception will be re-thrown to the caller of write.

    Nested transactions (calling write within write) is not possible.

    Type Parameters

    • T

    Parameters

    • callback: (() => T)

      Function to be called inside a write transaction.

        • (): T
        • Returns T

    Returns T

    Returned value from the callback.

  • Writes a compacted copy of the Realm with the given configuration.

    The destination file cannot already exist. All conversions between synced and non-synced Realms are supported, and will be performed according to the config parameter, which describes the desired output.

    Note that if this method is called from within a write transaction, the current data is written, not the data from the point when the previous write transaction was committed.

    Parameters

    • config: Configuration

      Realm configuration that describes the output realm.

    Returns void

  • Private

    Clears the state by closing and deleting any Realm in the default directory and logout all users. NOTE: Not a part of the public API and it's primarily used from the library's tests.

    Returns void

  • Copy any Realm files (i.e. *.realm) bundled with the application from the application directory into the application's documents directory, so that they can be opened and used by Realm. If the file already exists in the documents directory, it will not be overwritten, so this can safely be called multiple times.

    This should be called before opening the Realm, in order to move the bundled Realm files into a place where they can be written to.

    Returns void

    Example

    // Given a bundled file, example.realm, this will copy example.realm (and any other .realm files)
    // from the app bundle into the app's documents directory. If the file already exists, it will
    // not be overwritten, so it is safe to call this every time the app starts.
    Realm.copyBundledRealmFiles();

    const realm = await Realm.open({
    // This will open example.realm from the documents directory, with the bundled data in.
    path: "example.realm"
    });

    This is only implemented for React Native.

    Throws

    an Error If an I/O error occurred or method is not implemented.

  • Creates a template object for a Realm model class where all optional fields are undefined and all required fields have the default value for the given data type, either the value set by the default property in the schema or the default value for the datatype if the schema doesn't specify one, i.e. 0, false and "".

    Type Parameters

    • T extends Record<string, unknown>

    Parameters

    • objectSchema: ObjectSchema

      Schema describing the object that should be created.

    Returns T

  • Delete the Realm file for the given configuration.

    Parameters

    • config: Configuration

      The configuration for the Realm being deleted.

    Returns void

    Throws

    An Error if anything in the provided config is invalid.

  • Checks if the Realm already exists on disk.

    Parameters

    • path: string

      The path for a Realm.

    Returns boolean

    true if the Realm exists on the device, false if not.

    Throws

    An Error if anything in the provided path is invalid.

  • Checks if the Realm already exists on disk.

    Parameters

    Returns boolean

    true if the Realm exists on the device, false if not.

    Throws

    An Error if anything in the provided config is invalid.

  • Open the default Realm asynchronously with a promise.

    Returns ProgressRealmPromise

    A promise that will be resolved with the Realm instance when it's available.

  • Open a Realm asynchronously with a promise. If the Realm is synced, it will be fully synchronized before it is available.

    Parameters

    • path: string

      The path for the Realm.

    Returns ProgressRealmPromise

    A promise that will be resolved with the Realm instance when it's available.

  • Open a Realm asynchronously with a promise. If the Realm is synced, it will be fully synchronized before it is available. In the case of query-based sync, Configuration.schema is required. An exception will be thrown if Configuration.schema is not defined.

    Parameters

    Returns ProgressRealmPromise

    A promise that will be resolved with the Realm instance when it's available.

    Throws

    An Error if anything in the provided config is invalid.

  • Get the current schema version of the Realm at the given path.

    Parameters

    • path: string

      The path to the file where the Realm database is stored.

    • Optional encryptionKey: ArrayBuffer | ArrayBufferView

      Required only when accessing encrypted Realms.

    Returns number

    Version of the schema as an integer, or -1 if no Realm exists at path.

    Throws

    An Error if passing an invalid or non-matching encryption key.

    Since

    0.11.0

  • Sets the log level.

    Parameters

    • level: LogLevel

      The log level to be used by the logger. The default value is info.

    • Optional category: "Realm" | "Realm.Storage" | "Realm.Storage.Transaction" | "Realm.Storage.Query" | "Realm.Storage.Object" | "Realm.Storage.Notification" | "Realm.Sync" | "Realm.Sync.Client" | "Realm.Sync.Client.Session" | "Realm.Sync.Client.Changeset" | "Realm.Sync.Client.Network" | "Realm.Sync.Client.Reset" | "Realm.Sync.Server" | "Realm.App" | "Realm.SDK"

      The category to set the log level for. If omitted, the log level is set for all categories ("Realm").

    Returns void

    Note

    The log level can be changed during the lifetime of the application.

    Since

    12.0.0

    Example

    Realm.setLogLevel("all");
    
  • Sets the logger callback.

    Parameters

    • loggerCallback: LoggerCallback2

      The callback invoked by the logger. The default callback uses console.log, console.warn and console.error, depending on the level of the message.

    Returns void

    Note

    The logger callback needs to be set up before opening the first Realm.

    Since

    12.0.0

    Example

    Realm.setLogger(({ category, level, message }) => {
    console.log(`[${category} - ${level}] ${message}`);
    });
  • Sets the logger callback.

    Parameters

    • loggerCallback: LoggerCallback1

      The callback invoked by the logger. The default callback uses console.log, console.warn and console.error, depending on the level of the message.

    Returns void

    Note

    The logger callback needs to be set up before opening the first Realm.

    Since

    12.0.0

    Deprecated

    Pass a callback taking a single object argument instead.

    Example

    Realm.setLogger((level, message) => {
    console.log(`[${level}] ${message}`);
    });
  • Closes all Realms, cancels all pending Realm.open calls, clears internal caches, resets the logger and collects garbage. Call this method to free up the event loop and allow Node.js to perform a graceful exit.

    Returns void

Generated using TypeDoc