Create a new Realm instance, at the default path.
An Error when an incompatible synced Realm is opened.
Create a new Realm instance at the provided path.
Required when first creating the Realm.
An Error if the Realm cannot be opened at the provided path.
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.
Required when first creating the Realm.
An Error if anything in the provided config is invalid.
An Error when an incompatible synced Realm is opened.
Private
beforePrivate
changePrivate
classesPrivate
handleUpdate subscriptions with the initial subscriptions if needed.
The initial subscriptions.
Whether the realm already exists.
Private
schemaPrivate
schemaReadonly
syncThe sync session if this is a synced Realm
Static
defaultStatic
Private
determineStatic
Private
determineWhen the path is relative and the config contains a sync object, Core will replace any existing file extension or add the ".realm" suffix.
Static
Private
determineStatic
Private
extractStatic
Private
internalsStatic
Private
normalizeTODO: Consider breaking this by ensuring a ".realm" suffix (coordinating with other SDK teams in the process)
Static
Private
wrapIndicates if this Realm has been closed.
true
if closed, false
otherwise.
2.1.0
Indicates if this Realm contains any objects.
true
if empty, false
otherwise.
1.10.0
Indicates if this Realm was opened in-memory.
true
if this Realm is in-memory, false
otherwise.
Indicates if this Realm is in migration.
true
if in migration, false
otherwise
12.3.0
Indicates if this Realm is in a write transaction.
true
if in a write transaction, false
otherwise.
1.10.3
Indicates if this Realm was opened as read-only.
true
if this Realm is read-only, false
otherwise.
0.12.0
The path to the file where this Realm is stored.
A string containing the path to the file where this Realm is stored.
0.12.0
A normalized representation of the schema provided in the Configuration when this Realm was constructed.
An array of CanonicalObjectSchema describing all objects in this Realm.
0.12.0
The current schema version of the Realm.
The schema version of this Realm, as a number
.
0.12.0
The latest set of flexible sync subscriptions.
A SubscriptionSet object.
An Error if flexible sync is not enabled for this app.
Add a listener callback for the specified eventName.
The name of event that should cause the callback to be called.
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.
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.
An Error if already in write transaction
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;
}
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.
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.
A RealmObject or undefined
if the object is asymmetric.
Deletes a Realm model, including all of its objects. If called outside a migration function, schema and schemaVersion are updated.
The model name.
Searches for a Realm object by its primary key.
A RealmObject or null
if no object is found.
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.
0.14.0
Returns all objects of the given type in the Realm.
The type of Realm objects to retrieve.
Results that will live-update as objects are created, modified, and destroyed.
An Error if type passed into this method is invalid or if the type is marked embedded or asymmetric.
Remove all event listeners (restricted to the event eventName, if provided).
Optional
eventName: RealmEventNameThe name of the event whose listeners should be removed.
An Error when invalid event eventName is supplied.
Remove the listener callback for the specified event eventName.
The event name.
Function that was previously added as a listener for this event through the addListener method.
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.
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.
Realm configuration that describes the output realm.
Static
Private
clearStatic
copyCopy 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.
// 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.
an Error If an I/O error occurred or method is not implemented.
Static
createCreates 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 "".
Schema describing the object that should be created.
Static
deleteDelete the Realm file for the given configuration.
The configuration for the Realm being deleted.
An Error if anything in the provided config is invalid.
Static
existsChecks if the Realm already exists on disk.
The path for a Realm.
true
if the Realm exists on the device, false
if not.
An Error if anything in the provided path is invalid.
Checks if the Realm already exists on disk.
The configuration of a Realm.
true
if the Realm exists on the device, false
if not.
An Error if anything in the provided config is invalid.
Static
openOpen the default Realm asynchronously with a promise.
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.
The path for the Realm.
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.
The configuration for the Realm.
A promise that will be resolved with the Realm instance when it's available.
An Error if anything in the provided config is invalid.
Static
schemaGet the current schema version of the Realm at the given path.
The path to the file where the Realm database is stored.
Optional
encryptionKey: ArrayBuffer | ArrayBufferViewRequired only when accessing encrypted Realms.
Version of the schema as an integer, or -1
if no Realm exists at path.
An Error if passing an invalid or non-matching encryption key.
0.11.0
Static
setSets the log level.
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"
).
The log level can be changed during the lifetime of the application.
12.0.0
Realm.setLogLevel("all");
Static
setSets the logger callback.
The callback invoked by the logger. The default callback uses console.log
, console.warn
and console.error
, depending on the level of the message.
The logger callback needs to be set up before opening the first Realm.
12.0.0
Realm.setLogger(({ category, level, message }) => {
console.log(`[${category} - ${level}] ${message}`);
});
Sets the logger callback.
The callback invoked by the logger. The default callback uses console.log
, console.warn
and console.error
, depending on the level of the message.
The logger callback needs to be set up before opening the first Realm.
12.0.0
Pass a callback taking a single object argument instead.
Realm.setLogger((level, message) => {
console.log(`[${level}] ${message}`);
});
Static
shutdownCloses 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.
Generated using TypeDoc
The Realm database.