Inherits from RLMObjectBase
Declared in RLMObject.h

Overview

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.

Tasks

Creating & Initializing Objects

Customizing your Objects

Getting & Querying Objects from the Default Realm

Querying Specific Realms

Properties

invalidated

Indicates if an object can no longer be accessed.

@property (nonatomic, readonly, getter=isInvalidated) BOOL invalidated

Discussion

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.

Declared In

RLMObject.h

objectSchema

The ObjectSchema which lists the persisted properties for this object.

@property (nonatomic, readonly) RLMObjectSchema *objectSchema

Declared In

RLMObject.h

realm

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

@property (nonatomic, readonly, nullable) RLMRealm *realm

Declared In

RLMObject.h

Class Methods

allObjects

Get all objects of this type from the default Realm.

+ (RLMResults *)allObjects

Return Value

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

Declared In

RLMObject.h

allObjectsInRealm:

Get all objects of this type from the specified Realm.

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

Parameters

realm

The Realm instance to query.

Return Value

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

Declared In

RLMObject.h

className

Helper to return the class name for an RLMObject subclass.

+ (NSString *)className

Return Value

The class name for the model class.

Discussion

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

Declared In

RLMObject.h

createInDefaultRealmWithValue:

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

+ (instancetype)createInDefaultRealmWithValue:(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.

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

Discussion

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.

See Also

Declared In

RLMObject.h

createInRealm:withValue:

Create an RLMObject in a Realm with a given object.

+ (instancetype)createInRealm:(RLMRealm *)realm withValue:(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.

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

Discussion

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 Also

Declared In

RLMObject.h

createOrUpdateInDefaultRealmWithValue:

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

+ (instancetype)createOrUpdateInDefaultRealmWithValue:(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.

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

Discussion

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.

See Also

Declared In

RLMObject.h

createOrUpdateInRealm:withValue:

Create or update an RLMObject with a given object.

+ (instancetype)createOrUpdateInRealm:(RLMRealm *)realm withValue:(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.

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

Discussion

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.

See Also

Declared In

RLMObject.h

defaultPropertyValues

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

+ (nullable NSDictionary *)defaultPropertyValues

Return Value

NSDictionary mapping property names to their default values.

Declared In

RLMObject.h

ignoredProperties

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

+ (nullable NSArray *)ignoredProperties

Return Value

NSArray of property names to ignore.

Declared In

RLMObject.h

indexedProperties

Return an array of property names for properties which should be indexed. Only supported for string and int properties.

+ (NSArray *)indexedProperties

Return Value

NSArray of property names.

Declared In

RLMObject.h

objectForPrimaryKey:

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

+ (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.

Discussion

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 Also

Declared In

RLMObject.h

objectInRealm:forPrimaryKey:

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

+ (nullable instancetype)objectInRealm:(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.

Discussion

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 Also

Declared In

RLMObject.h

objectsInRealm:where:

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

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

Parameters

realm

The Realm instance to query.

predicateFormat

The predicate format string which can accept variable arguments.

Return Value

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

Declared In

RLMObject.h

objectsInRealm:withPredicate:

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

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

Parameters

realm

The Realm instance to query.

predicate

The predicate to filter the objects.

Return Value

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

Declared In

RLMObject.h

objectsWhere:

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

+ (RLMResults *)objectsWhere:(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

Declared In

RLMObject.h

objectsWithPredicate:

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

+ (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

Declared In

RLMObject.h

primaryKey

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.

+ (nullable NSString *)primaryKey

Return Value

Name of the property designated as the primary key.

Declared In

RLMObject.h

requiredProperties

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

+ (NSArray *)requiredProperties

Return Value

NSArray of property names that are required.

Discussion

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.

Declared In

RLMObject.h

Instance Methods

init

Initialize a standalone RLMObject

- (instancetype)init

Discussion

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

See Also

Declared In

RLMObject.h

initWithValue:

Initialize a standalone RLMObject with values from an NSArray or NSDictionary

- (instancetype)initWithValue:(id)value

Discussion

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

See Also

Declared In

RLMObject.h

isEqualToObject:

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.

- (BOOL)isEqualToObject:(RLMObject *)object

Parameters

object

The object to compare to.

Return Value

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

Declared In

RLMObject.h

linkingObjectsOfClass:forProperty:

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 relatshionship value for RLMObject and RLMArray properties.

- (NSArray *)linkingObjectsOfClass:(NSString *)className forProperty:(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 thier value for the property property.

Declared In

RLMObject.h