Realm

Related Classes

Collection

List

Object

Results

Realm.defaultPath

static

The default path where to create and access the Realm file.

Type:

string

path

readonly

The path to the file where this Realm is stored.

Type:

string

Since: 0.12.0

readOnly

readonly

Indicates if this Realm was opened as read-only.

Type:

boolean

Since: 0.12.0

schema

readonly

A normalized representation of the schema provided in the Configuration when this Realm was constructed.

Type:

[ObjectSchema, ...]

Since: 0.12.0

schemaVersion

readonly

The current schema version of this Realm.

Type:

number

Since: 0.12.0

new Realm(config)

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.

Parameters:

• config optional
• Type: Configuration

• Required when first creating the Realm.

Realm.schemaVersion(path, encryptionKey)number

static

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

Parameters:

• path
• Type: string

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

• encryptionKey optional
• Type: ArrayBuffer or ArrayBufferView

• Required only when accessing encrypted Realms.

Throws:

• Error

  • When passing an invalid or non-matching encryption key.

Returns: number version of the schema, or -1 if no Realm exists at path.

addListener(name, callback)

Add a listener callback for the specified event name.

Parameters:

• name
• Type: string

• The name of event that should cause the callback to be called. Currently, only the "change" event supported.

• callback
• Type: function

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

Throws:

• Error

  • If an invalid event name is supplied, or if callback is not a function.

close()

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.

create(type, properties, update)Realm.Object

Create a new Realm object of the given type and with the specified properties.

Parameters:

• type
• Type: ObjectType

• The type of Realm object to create.

• properties
• Type: Object

• Property values for all required properties without a default value.

• update optional
• Type: boolean
• Default: false

• Signals that an existing object with matching primary key should be updated. Only the primary key property and properties which should be updated need to be specified. All missing property values will remain unchanged.

Returns: Realm.Object

delete(object)

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

Parameters:

• object
• Type: Realm.Object or [Realm.Object, ...] or Realm.List or Realm.Results

deleteAll()

WARNING: This will delete all objects in the Realm!

objectForPrimaryKey(type, key)Realm.Object or undefined

Searches for a Realm object by its primary key.

Parameters:

• type
• Type: ObjectType

• The type of Realm object to search for.

• key
• Type: number or string

• The primary key value of the object to search for.

Throws:

• Error

  • If type passed into this method is invalid or if the object type did not have a primaryKey specified in its ObjectSchema.

Returns: Realm.Object or undefined if no object is found.

Since: 0.14.0

objects(type)Realm.Results

Returns all objects of the given type in the Realm.

Parameters:

• type
• Type: ObjectType

• The type of Realm objects to retrieve.

Throws:

• Error

  • If type passed into this method is invalid.

Returns: Realm.Results that will live-update as objects are created and destroyed.

removeAllListeners(name)

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

Parameters:

• name optional
• Type: string

• The name of the event whose listeners should be removed. Currently, only the "change" event supported.

Throws:

• Error

  • When invalid event name is supplied

removeListener(name, callback)

Remove the listener callback for the specfied event name.

Parameters:

• name
• Type: string

• The event name. Currently, only the "change" event supported.

• callback
• Type: function

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

Throws:

• Error

  • If an invalid event name is supplied, or if callback is not a function.

write(callback)

Synchronously call the provided callback inside a write transaction.

Parameters:

• callback
• Type: function

Configuration

This describes the different options used to create a Realm instance.

Type:

Object

Properties:

• encryptionKey optional
• Type: ArrayBuffer or ArrayBufferView

• The 512-bit (64-byte) encryption key used to encrypt and decrypt all data in the Realm.

• migration optional
• Type: function

• The function to run if a migration is needed. This function should provide all the logic for converting data models from previous schemas to the new schema. This function takes two arguments:

  • oldRealm - The Realm before migration is performed.
  • newRealm - The Realm that uses the latest schema, which should be modified as necessary.

• path optional
• Type: string
• Default: Realm.defaultPath

• The path to the file where the Realm database should be stored.

• readOnly optional
• Type: boolean
• Default: false

• Specifies if this Realm should be opened as read-only.

• schema optional
• Type: [(ObjectClass | ObjectSchema), ...]

• Specifies all the object types in this Realm. Required when first creating a Realm at this path.

• schemaVersion optional
• Type: number

• Required (and must be incremented) after changing the schema.

ObjectClass

Realm objects will inherit methods, getters, and setters from the prototype of this constructor. It is highly recommended that this constructor inherit from Realm.Object.

Type:

Class

Properties:

• schema
• Type: ObjectSchema

• Static property specifying object schema information.

ObjectSchema

Type:

Object

Properties:

• name
• Type: string

• Represents the object type.

• primaryKey optional
• Type: string

• The name of a "string" or "int" property that must be unique across all objects of this type within the same Realm.

• properties
• Type: {<string>: (PropertyType | ObjectSchemaProperty), ...}

• An object where the keys are property names and the values represent the property type.

ObjectSchemaProperty

Type:

Object

Properties:

• type
• Type: PropertyType

• The type of this property.

• objectType optional
• Type: string

• Required when type is "list", and must match the type of an object in the same schema.

• default optional
• Type: any

• The default value for this property on creation when not otherwise specified.

• optional optional
• Type: boolean

• Signals if this property may be assigned null or undefined.

• indexed optional
• Type: boolean

• Signals if this property should be indexed. Only supported for "string", "int", and "bool" properties.

ObjectType

The type of an object may either be specified as a string equal to the name in a ObjectSchema definition, or a constructor that was specified in the configuration schema.

Type:

string or ObjectClass

PropertyType

A property type may be specified as one of the standard builtin types, or as an object type inside the same schema.

Type:

"bool" or "int" or "float" or "double" or "string" or "date" or "data" or "list" or "<ObjectType>"

Properties:

• "bool"
• Type: boolean

• Property value may either be true or false.

• "int"
• Type: number

• Property may be assigned any number, but will be stored as a round integer, meaning anything after the decimal will be truncated.

• "float"
• Type: number

• Property may be assigned any number, but will be stored as a float, which may result in a loss of precision.

• "double"
• Type: number

• Property may be assigned any number, and will have no loss of precision.

• "string"
• Type: string

• Property value may be any arbitrary string.

• "date"
• Type: Date

• Property may be assigned any Date instance.

• "data"
• Type: ArrayBuffer

• Property may either be assigned an ArrayBuffer or ArrayBufferView (e.g. DataView, Int8Array, Float32Array, etc.) instance, but will always be returned as an ArrayBuffer.

• "list"
• Type: Realm.List

• Property may be assigned any ordered collection (e.g. Array, Realm.List, Realm.Results) of objects all matching the objectType specified in the ObjectSchemaProperty.

• "<ObjectType>"
• Type: Realm.Object

• A string that matches the name of an object in the same schema (see ObjectSchema) – this property may be assigned any object of this type from inside the same Realm, and will always be optional (meaning it may also be assigned null or undefined).