RLMObject

@interface RLMObject : RLMObjectBase

In Realm you define your model classes by subclassing RLMObject and adding properties to be persisted. You then instantiate and use your custom subclasses instead of using the RLMObject class directly.

// Dog.h
@interface Dog : RLMObject
@property NSString *name;
@property BOOL      adopted;
@end

// Dog.m
@implementation Dog
@end //none needed

Supported property types

  • NSString
  • NSInteger, int, long, float, and double
  • BOOL or bool
  • NSDate
  • NSData
  • NSNumber<X>, where X is one of RLMInt, RLMFloat, RLMDouble or RLMBool, for optional number properties
  • RLMObject subclasses, so you can have many-to-one relationships.
  • RLMArray<X>, where X is an RLMObject subclass, so you can have many-to-many relationships.

Querying

You can query an object directly via the class methods: allObjects, objectsWhere:, and objectsWithPredicate:. These methods allow you to easily query a custom subclass for instances of this class in the default Realm. To search in a Realm other than the default Realm use the interface on an RLMRealm instance.

Relationships

See our Cocoa guide for more details.

Key-Value Observing

All RLMObject properties (including properties you create in subclasses) are Key-Value Observing compliant, except for realm and objectSchema. There are several Realm-specific things to keep in mind when observing Realm objects:

  1. Unlike NSMutableArray properties, RLMArray properties do not require using the proxy object returned from -mutableArrayValueForKey:, or defining KVC mutation methods on the containing class. You can simply call methods on the RLMArray directly and the changes will be observed by the containing object.
  2. Standalone RLMObjects cannot be added to a Realm while they have any observed properties.
  3. Modifying persisted RLMObjects in -observeValueForKeyPath:ofObject:change:context: is problematic. Properties may change when the Realm is not in a write transaction (for example, when -[RLMRealm refresh] is called after changes are made on a different thread), and notifications sent prior to the change being applied (when NSKeyValueObservingOptionPrior is used) may be sent at times when you cannot begin a write transaction.

Creating & Initializing Objects

  • Initialize a standalone RLMObject

    Initialize an unpersisted instance of this object. Call addObject: on an RLMRealm to add standalone object to a realm.

    See

    [RLMRealm addObject:]:

    Declaration

    Objective‑C

    - (nonnull instancetype)init;
    Show on GitHub

  • Initialize a standalone RLMObject with values from an NSArray or NSDictionary

    Initialize an unpersisted instance of this object. Call addObject: on an RLMRealm to add standalone object to a realm.

    See

    [RLMRealm addObject:]:

    Declaration

    Objective‑C

    - (nonnull instancetype)initWithValue:(nonnull id)value;
    Show on GitHub

  • Helper to return the class name for an RLMObject subclass.

    Warning

    Do not override. Realm relies on this method returning the exact class name.

    Declaration

    Objective‑C

    + (nonnull NSString *)className;

    Return Value

    The class name for the model class.

    Show on GitHub

  • Create an RLMObject in the default Realm with a given value.

    Creates an instance of this object and adds it to the default Realm populating the object with the given value.

    If nested objects are included in the argument, createInDefaultRealmWithValue: will be called on them.

    When passing in an NSArray, all properties must be present, valid and in the same order as the properties defined in the model.

    See

    defaultPropertyValues

    Declaration

    Objective‑C

    + (nonnull instancetype)createInDefaultRealmWithValue:(nonnull id)value;

    Parameters

    value

    The value used to populate the object. This can be any key/value coding compliant object, or a JSON object such as those returned from the methods in NSJSONSerialization, or an NSArray with one object for each persisted property. An exception will be thrown if any required properties are not present and no default is set.
    Show on GitHub

  • Create an RLMObject in a Realm with a given object.

    Creates an instance of this object and adds it to the given Realm populating the object with the given object.

    If nested objects are included in the argument, createInRealm:withValue: will be called on them.

    See

    defaultPropertyValues

    Declaration

    Objective‑C

    + (nonnull instancetype)createInRealm:(nonnull RLMRealm *)realm
                            withValue:(nonnull id)value;

    Parameters

    realm

    The Realm in which this object is persisted.
    value

    The value used to populate the object. This can be any key/value coding compliant object, or a JSON object such as those returned from the methods in NSJSONSerialization, or an NSArray with one object for each persisted property. An exception will be thrown if any required properties are not present and no default is set.
    Show on GitHub

  • Create or update an RLMObject in the default Realm with a given object.

    This method can only be called on object types with a primary key defined. If there is already an object with the same primary key value in the default RLMRealm its values are updated and the object is returned. Otherwise this creates and populates a new instance of this object in the default Realm.

    If nested objects are included in the argument, createOrUpdateInDefaultRealmWithValue: will be called on them if have a primary key (createInDefaultRealmWithValue: otherwise).

    This is a no-op if the argument is an RLMObject of the same type already backed by the target realm.

    When passing in an NSArray, all properties must be present, valid and in the same order as the properties defined in the model.

    See

    defaultPropertyValues, primaryKey

    Declaration

    Objective‑C

    + (nonnull instancetype)createOrUpdateInDefaultRealmWithValue:(nonnull id)value;

    Parameters

    value

    The value used to populate the object. This can be any key/value coding compliant object, or a JSON object such as those returned from the methods in NSJSONSerialization, or an NSArray with one object for each persisted property. An exception will be thrown if any required properties are not present and no default is set.
    Show on GitHub

  • Create or update an RLMObject with a given object.

    This method can only be called on object types with a primary key defined. If there is already an object with the same primary key value in the provided RLMRealm its values are updated and the object is returned. Otherwise this creates and populates a new instance of this object in the provided Realm.

    If nested objects are included in the argument, createOrUpdateInRealm:withValue: will be called on them if have a primary key (createInRealm:withValue: otherwise).

    This is a no-op if the argument is an RLMObject of the same type already backed by the target realm.

    When passing in an NSArray, all properties must be present, valid and in the same order as the properties defined in the model.

    See

    defaultPropertyValues, primaryKey

    Declaration

    Objective‑C

    + (nonnull instancetype)createOrUpdateInRealm:(nonnull RLMRealm *)realm
                                    withValue:(nonnull id)value;

    Parameters

    realm

    The Realm in which this object is persisted.
    value

    The value used to populate the object. This can be any key/value coding compliant object, or a JSON object such as those returned from the methods in NSJSONSerialization, or an NSArray with one object for each persisted property. An exception will be thrown if any required properties are not present and no default is set.
    Show on GitHub

Properties

  • The Realm in which this object is persisted. Returns nil for standalone objects.

    Declaration

    Objective‑C

    @property (readonly, nonatomic, nullable) RLMRealm *realm;
    Show on GitHub

  • The ObjectSchema which lists the persisted properties for this object.

    Declaration

    Objective‑C

    @property (readonly, nonatomic) RLMObjectSchema *_Nonnull objectSchema;
    Show on GitHub

  • Indicates if an object can no longer be accessed.

    An object can no longer be accessed if the object has been deleted from the containing realm or if invalidate is called on the containing realm.

    Declaration

    Objective‑C

    @property (readonly, getter=isInvalidated, nonatomic) BOOL invalidated;
    Show on GitHub

Customizing your Objects

  • Return an array of property names for properties which should be indexed. Only supported for string and int properties. - returns: NSArray of property names.

    Declaration

    Objective‑C

    + (nonnull NSArray<NSString *> *)indexedProperties;

    Return Value

    NSArray of property names.

    Show on GitHub

  • Implement to indicate the default values to be used for each property.

    Declaration

    Objective‑C

    + (nullable NSDictionary *)defaultPropertyValues;

    Return Value

    NSDictionary mapping property names to their default values.

    Show on GitHub

  • Implement to designate a property as the primary key for an RLMObject subclass. Only properties of type RLMPropertyTypeString and RLMPropertyTypeInt can be designated as the primary key. Primary key properties enforce uniqueness for each value whenever the property is set which incurs some overhead. Indexes are created automatically for primary key properties.

    Declaration

    Objective‑C

    + (nullable NSString *)primaryKey;

    Return Value

    Name of the property designated as the primary key.

    Show on GitHub

  • Implement to return an array of property names to ignore. These properties will not be persisted and are treated as transient.

    Declaration

    Objective‑C

    + (nullable NSArray<NSString *> *)ignoredProperties;

    Return Value

    NSArray of property names to ignore.

    Show on GitHub

  • Implement to return an array of property names that should not allow storing nil.

    By default, all properties of a type that support storing nil are considered optional properties. To require that an object in a Realm always have a non-nil value for a property, add the name of the property to the array returned from this method.

    Currently Object properties cannot be required. Array and NSNumber properties can, but it makes little sense to do so: arrays do not support storing nil, and if you want a non-optional number you should instead use the primitive type.

    Declaration

    Objective‑C

    + (nonnull NSArray<NSString *> *)requiredProperties;

    Return Value

    NSArray of property names that are required.

    Show on GitHub

Getting & Querying Objects from the Default Realm

  • Get all objects of this type from the default Realm.

    Declaration

    Objective‑C

    + (nonnull RLMResults *)allObjects;

    Return Value

    An RLMResults of all objects of this type in the default Realm.

    Show on GitHub

  • Get objects matching the given predicate for this type from the default Realm.

    Declaration

    Objective‑C

    + (nonnull RLMResults *)objectsWhere:(nonnull NSString *)predicateFormat, ...;

    Parameters

    predicateFormat

    The predicate format string which can accept variable arguments.

    Return Value

    An RLMResults of objects of the subclass type in the default Realm that match the given predicate

    Show on GitHub

  • Get objects matching the given predicate for this type from the default Realm.

    Declaration

    Objective‑C

    + (nonnull RLMResults *)objectsWithPredicate:(nullable NSPredicate *)predicate;

    Parameters

    predicate

    The predicate to filter the objects.

    Return Value

    An RLMResults of objects of the subclass type in the default Realm that match the given predicate

    Show on GitHub

  • Get the single object with the given primary key from the default Realm.

    Returns the object from the default Realm which has the given primary key, or nil if the object does not exist. This is slightly faster than the otherwise equivalent [[SubclassName objectsWhere:@"primaryKeyPropertyName = %@", key] firstObject].

    This method requires that primaryKey be overridden on the receiving subclass.

    See

    -primaryKey

    Declaration

    Objective‑C

    + (nullable instancetype)objectForPrimaryKey:(nullable id)primaryKey;

    Return Value

    An object of the subclass type or nil if an object with the given primary key does not exist.

    Show on GitHub

Querying Specific Realms

  • Get all objects of this type from the specified Realm.

    Declaration

    Objective‑C

    + (nonnull RLMResults *)allObjectsInRealm:(nonnull RLMRealm *)realm;

    Parameters

    realm

    The Realm instance to query.

    Return Value

    An RLMResults of all objects of this type in the specified Realm.

    Show on GitHub

  • Get objects matching the given predicate for this type from the specified Realm.

    Declaration

    Objective‑C

    + (nonnull RLMResults *)objectsInRealm:(nonnull RLMRealm *)realm
                                 where:(nonnull NSString *)predicateFormat, ...;

    Parameters

    predicateFormat

    The predicate format string which can accept variable arguments.
    realm

    The Realm instance to query.

    Return Value

    An RLMResults of objects of the subclass type in the specified Realm that match the given predicate

    Show on GitHub

  • Get objects matching the given predicate for this type from the specified Realm.

    Declaration

    Objective‑C

    + (nonnull RLMResults *)objectsInRealm:(nonnull RLMRealm *)realm
                         withPredicate:(nullable NSPredicate *)predicate;

    Parameters

    predicate

    The predicate to filter the objects.
    realm

    The Realm instance to query.

    Return Value

    An RLMResults of objects of the subclass type in the specified Realm that match the given predicate

    Show on GitHub

  • Get the single object with the given primary key from the specified Realm.

    Returns the object from the specified Realm which has the given primary key, or nil if the object does not exist. This is slightly faster than the otherwise equivalent [[SubclassName objectsInRealm:realm where:@"primaryKeyPropertyName = %@", key] firstObject].

    This method requires that primaryKey be overridden on the receiving subclass.

    See

    -primaryKey

    Declaration

    Objective‑C

    + (nullable instancetype)objectInRealm:(nonnull RLMRealm *)realm
                         forPrimaryKey:(nullable id)primaryKey;

    Return Value

    An object of the subclass type or nil if an object with the given primary key does not exist.

    Show on GitHub

Other Instance Methods

  • Get an NSArray of objects of type className which have this object as the given property value. This can be used to get the inverse relationship value for RLMObject and RLMArray properties.

    Declaration

    Objective‑C

    - (nonnull NSArray *)linkingObjectsOfClass:(nonnull NSString *)className
                               forProperty:(nonnull NSString *)property;

    Parameters

    className

    The type of object on which the relationship to query is defined.
    property

    The name of the property which defines the relationship.

    Return Value

    An NSArray of objects of type className which have this object as their value for the property property.

    Show on GitHub

  • Returns YES if another RLMObject points to the same object in an RLMRealm. For RLMObject types with a primary, key, isEqual: is overridden to use this method (along with a corresponding implementation for hash.

    Declaration

    Objective‑C

    - (BOOL)isEqualToObject:(nonnull RLMObject *)object;

    Parameters

    object

    The object to compare to.

    Return Value

    YES if the object represents the same object in the same RLMRealm.

    Show on GitHub