CRUD - Read - Swift SDK

Read Characteristics

When you design your app's data access patterns around the following three key characteristics of reads in Realm, you can be confident you are reading data as efficiently as possible.

Limiting Query Results

As a result of lazy evaluation, you do not need any special mechanism to limit query results with Realm. For example, if your query matches thousands of objects, but you only want to load the first ten, simply access only the first ten elements of the results collection.

Pagination

Thanks to lazy evaluation, the common task of pagination becomes quite simple. For example, suppose you have a results collection associated with a query that matches thousands of objects in your realm. You display one hundred objects per page. To advance to any page, simply access the elements of the results collection starting at the index that corresponds to the target page.

About The Examples On This Page

The examples on this page use the following models:

Find a Specific Object by Primary Key

Query All Objects of a Given Type

Filter Queries Based on Object Properties

A filter selects a subset of results based on the value(s) of one or more object properties. Realm provides a full-featured query engine that you can use to define filters.

Filter on Object ID Properties

The types in your predicate must match the types of the properties. Avoid comparing ObjectId properties to strings, as Realm does not automatically convert strings to ObjectIds.

Query a Relationship

You can query through a relationship the same way you would access a member of a regular Swift or Objective-C object.

Query an Inverse Relationship

You can query through an inverse relationship the same way you would access a member of a regular Swift or Objective-C object.

Query a Collection on Embedded Object Properties

Use dot notation to filter or sort a collection of objects based on an embedded object property value:

Query a Map Property

You can iterate and check the values of a realm map as you would a standard Dictionary:

let realm = try! Realm()
let dogs = realm.objects(Dog.self)
// Find dogs who have favorite parks
let dogsWithFavoriteParks = dogs.where {
    $0.favoriteParksByCity.count >= 1
}
for dog in dogsWithFavoriteParks {
    // Check if an entry exists
    if dog.favoriteParksByCity.keys.contains("Chicago") {
        print("\(dog.name) has a favorite park in Chicago")
    }
    // Iterate over entries
    for element in dog.favoriteParksByCity {
        print("\(dog.name)'s favorite park in \(element.key) is \(element.value)")
    }
}

Query a MutableSet Property

You can query a MutableSet to check if it contains an element. If you are working with multiple sets, you can check for the intersection of two sets, or check whether one set is a subset of the other set.

let realm = try! Realm()
// Find dogs who have visited New York
let newYorkDogs = realm.objects(Dog.self).where {
    $0.citiesVisited.contains("New York")
}
// Get some information about the cities they have visited
for dog in newYorkDogs {
    print("Cities \(dog.name) has visited: \(dog.citiesVisited)")
}
// Check whether two dogs have visited some of the same cities.
// Use "intersects" to find out whether the values of the two sets share common elements.
let isInBothCitiesVisited = (dog.citiesVisited.intersects(dog2.citiesVisited))
print("The two dogs have visited some of the same cities: \(isInBothCitiesVisited)")
// Prints "The two dogs have visited some of the same cities: true"
// Or you can check whether a set is a subset of another set. In this example,
// the first dog has visited "New York" and "Toronto", while dog2 has visited both of
// those but also "Toronto" and "Boston".
let isSubset = (dog.citiesVisited.isSubset(of: dog2.citiesVisited))
print("\(dog.name)'s set of cities visited is a subset of \(dog2.name)'s: \(isSubset)")
// Prints "Maui's set of cities visited is a subset of Lita's: true"

Read and Query AnyRealmValue Property

When you read an AnyRealmValue property, check the value's type before doing anything with it. The Realm Swift SDK provides an AnyRealmValue enum that iterates through all of the types the AnyRealmValue can store.

let realm = try! Realm()
let dogs = realm.objects(Dog.self)
for dog in dogs {
    // Verify the type of the ``AnyRealmProperty`` when attempting to get it. This
    // returns an object whose property contains the matched type.
    // If you only care about one type, check for that type.
    if case let .string(companion) = dog.companion {
        print("\(dog.name)'s companion is: \(companion)")
        // Prints "Wolfie's companion is: Fluffy the Cat"
    }
    // Or if you want to do something with multiple types of data
    // that could be in the value, switch on the type.
    switch dog.companion {
    case .string:
        print("\(dog.name)'s companion is: \(dog.companion)")
        // Prints "Wolfie's companion is: string("Fluffy the Cat")
    case .object:
        print("\(dog.name)'s companion is: \(dog.companion)")
        // Prints "Fido's companion is: object(Dog { name = Spot })"
    case .none:
        print("\(dog.name) has no companion")
        // Prints "Rex has no companion" and "Spot has no companion"
    default:
        print("\(dog.name)'s companion is another type.")
    }
}

You can compare these mixed value types:

• Numeric: int, bool, float, double, decimal

• Byte-based: string, binary

• Time-based: timestamp, objectId

When using the AnyRealmValue mixed data type, keep these things in mind:

• equals queries match on value and type

• not equals queries match objects with either different values or different types

• realm converts comparable numeric properties where possible. For example, in a mixed type field, 1 matches all of 1.0, 1, and true.

• String properties do not match numeric queries. For example, in a mixed type field, 1 does not match "1". "1" does not match 1, 1.0, or true.

Query Geospatial Data

The Swift SDK provides several shapes to simplify querying geospatial data. You can use the GeoCircle, GeoBox, and GeoPolygon shapes to set the boundaries for your geospatial data queries.

The SDK provides two specialized non-persistable data types to define shapes:

• GeoPoint: A struct that represents the coordinates of a point formed by a pair of doubles consisting of these values:

  • Latitude: ranges between -90 and 90 degrees, inclusive.

  • Longitude: ranges between -180 and 180 degrees, inclusive.

• RLMDistance: A helper struct to represent and convert a distance.

Query with Geospatial Shapes

You can then use these shapes in a geospatial query. You can query geospatial data in three ways:

• Using the .geoWithin() operator with the type-safe Realm Swift Query API

• Using a .filter() with RQL

• Using a .filter() with an NSPredicate query

The examples below show the results of queries using these two Company objects:

let company1 = Geospatial_Company()
company1.location = CustomGeoPoint(47.68, -122.35)
let company2 = Geospatial_Company(CustomGeoPoint(47.9, -121.85))

click to enlarge

Query a Custom Persistable Property

When you use type projection to map unsupported types to supported types, accessing those properties is often based on the persisted type.

let akcClub = realm.objects(Club.self).where {
    $0.name == "American Kennel Club"
}.first!
// You can use type-safe expressions to check for equality
XCTAssert(akcClub.url == URL(string: "https://akc.org")!)
let clubs = realm.objects(Club.self)
// You can use the persisted property type in NSPredicate query expressions
let akcByUrl = clubs.filter("url == 'https://akc.org'").first!
XCTAssert(akcByUrl.name == "American Kennel Club")