Class Realm

The Realm database.

Hierarchy

  • Realm

Constructors

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

    Throws

    An Error when an incompatible synced Realm is opened.

    Returns Realm

  • Create a new Realm instance at the provided path.

    Throws

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

    Throws

    An Error when an incompatible synced Realm is opened.

    Parameters

    • path: string

      Required when first creating the Realm.

    Returns Realm

  • Create a new Realm instance using the provided config. If a Realm does not yet exist at config.path (or 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.

    Throws

    An Error if anything in the provided config is invalid.

    Throws

    An Error when an incompatible synced Realm is opened.

    Parameters

    Returns Realm

Properties

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

Update subscriptions with the initial subscriptions if needed.

Param

The initial subscriptions.

Param

Whether the realm already exists.

schemaExtras: any
schemaListeners: any
syncSession: null | SyncSession

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
flags: {
    ALLOW_CLEAR_TEST_STATE: boolean;
    ALLOW_VALUES_ARRAYS: boolean;
    THROW_ON_GLOBAL_REALM: boolean;
}

Type declaration

  • ALLOW_CLEAR_TEST_STATE: boolean
  • ALLOW_VALUES_ARRAYS: boolean
  • THROW_ON_GLOBAL_REALM: boolean
index: IndexDecorator
internals: any
kmToRadians: ((km) => number)

Type declaration

    • (km): number
    • Converts the input kilometer value in radians.

      Parameters

      • km: number

        The kilometers to convert.

      Returns number

      The corresponding number of radians.

mapTo: MapToDecorator
miToRadians: ((mi) => number)

Type declaration

    • (mi): number
    • Converts the input miles value in radians.

      Parameters

      • mi: number

        The miles to convert.

      Returns number

      The corresponding number of radians.

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.

    Since

    2.1.0

    Returns boolean

    true if closed, false otherwise.

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

    Since

    1.10.0

    Returns boolean

    true if empty, false otherwise.

  • 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.

    Since

    12.3.0

    Returns boolean

    true if in migration, false otherwise

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

    Since

    1.10.3

    Returns boolean

    true if in a write transaction, false otherwise.

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

    Since

    0.12.0

    Returns boolean

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

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

    Since

    0.12.0

    Returns string

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

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

    Since

    0.12.0

    Returns number

    The schema version of this Realm, as a number.

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

    Throws

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

    Returns SubscriptionSet

    A SubscriptionSet object.

Methods

  • Type Parameters

    • T extends RealmObject<DefaultObject, never, T>

    Parameters

    • type: Constructor<T>
    • objectKey: string

    Returns undefined | T

  • Add a listener callback for the specified eventName.

    Throws

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

    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

  • 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.

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

    Returns void

  • Cancel a write transaction.

    See

    beginTransaction

    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.

    See

    beginTransaction

    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, never>>

      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 RealmObject<T, never> & T

    A RealmObject or undefined if the object is asymmetric.

  • Type Parameters

    • T extends RealmObject<any, never, T>

    Parameters

    • type: Constructor<T>
    • values: Partial<T> | Partial<Unmanaged<T, never>>
    • Optional mode: boolean | Never | Modified | All

    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.

    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

    • 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 | RealmObject<T, never> & T

    A RealmObject or null if no object is found.

  • Type Parameters

    • T extends RealmObject<any, never, T>

    Parameters

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

    Returns null | T

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

    Throws

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

    Type Parameters

    • T = DefaultObject

    Parameters

    • type: string

      The type of Realm objects to retrieve.

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

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

  • Type Parameters

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

    Parameters

    • type: Constructor<T>

    Returns Results<T>

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

    Throws

    An Error when invalid event eventName is supplied.

    Parameters

    • Optional eventName: RealmEventName

      The name of the event whose listeners should be removed.

    Returns void

  • Remove the listener callback for the specified event eventName.

    Throws

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

    Parameters

    • eventName: RealmEventName

      The event name.

    • callback: RealmListenerCallback

      Function that was previously added as a listener for this event through the addListener method.

    Returns void

  • 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.

    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.

    Returns void

  • 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.

    Throws

    An Error if anything in the provided config is invalid.

    Parameters

    • config: Configuration

      The configuration for the Realm being deleted.

    Returns void

  • Checks if the Realm already exists on disk.

    Throws

    An Error if anything in the provided config is invalid.

    Parameters

    • Optional arg: string | Configuration

      The configuration for the Realm or the path to it.

    Returns boolean

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

  • 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.scheme | config.schema is required. An exception will be thrown if Configuration.scheme | config.schema is not defined.

    Throws

    An Error if anything in the provided arg is invalid.

    Parameters

    • Optional arg: string | Configuration

      The configuration for the Realm or the path to it.

    Returns ProgressRealmPromise

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

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

    Throws

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

    Since

    0.11.0

    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.

  • Sets the log level.

    Note

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

    Since

    12.0.0

    Parameters

    • level: LogLevel

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

    Returns void

  • Sets the logger callback.

    Note

    The logger callback needs to be setup before opening the first realm.

    Since

    12.0.0

    Parameters

    • loggerCallback: LoggerCallback

      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

Generated using TypeDoc