Basic Queries

15min
Basic Queries
Introduction
In most use cases, we require to fetch data from a database with certain conditions. These conditions may include complex comparisons and ordering requirements. Thus, in any application, it is fundamental to construct efficient queries and, at the same time, the database has to be able to execute them as fast as possible.
The ParseSwift SDK does provide the necessary tools for you to construct any query according to the application requirements. In this tutorial, we explore these tools and use them in a real-world application.
This tutorial uses a basic app created in Xcode 12 and iOS 14.
At any time, you can access the complete Project via our GitHub repositories.
﻿iOS Example Repository﻿
Goal
To understand how to create basic queries to retrieve data from a Back4App Database.
Prerequisites
To complete this quickstart, you need:
Xcode.
An app created at Back4App.
Follow the New Parse App tutorial to learn how to create a Parse app at Back4App.
Note: Follow the Install Parse SDK (Swift) Tutorial to create an Xcode Project connected to Back4App.
Understanding our Constacts App
The project template is a Contacts App where the user adds a contact’s information to save it on a Back4App Database
﻿
On the app’s homescreen you will find a set of buttons for different types of queries. Using the + button located on the top-right side of the navigation bar, we can add as many Contacts as needed.
Quick reference of commands we are going to use
For this example, we use the object Contact﻿
Swift
 import Foundation
 import ParseSwift
3
 struct Contact: ParseObject {
     // Required properties from ParseObject protocol
     var originalData: Data?
     var objectId: String?
     var createdAt: Date?
     var updatedAt: Date?
    var ACL: ParseACL?
  
    // Custom fields for the contact's information
    var name: String?
    var birthday: Date?
    var numberOfFriends: Int?
    var favoriteFoods: [String]?
  
    ...
}
 import Foundation
 import ParseSwift
3
 struct Contact: ParseObject {
     // Required properties from ParseObject protocol
     var originalData: Data?
     var objectId: String?
     var createdAt: Date?
     var updatedAt: Date?
    var ACL: ParseACL?
  
    // Custom fields for the contact's information
    var name: String?
    var birthday: Date?
    var numberOfFriends: Int?
    var favoriteFoods: [String]?
  
    ...
}
﻿
The following methods will allows us to save and queryContactobjects:
Create contact
Query all
Query by name
Query by friend count
Query with ordering
//When creating and saving a new instance of Contact we can use
 var newContact: Contact = Contact(name: "John Doe", birthday: Date(), numberOfFriends: 5, favoriteFoods: ["Bread", "Pizza"])
2
 // Saves newContact on your Back4App Database synchronously and returns the new saved Item. It throws and error if something went wrong.
 let savedContact = try? newContact.save()
5
 // Saves newContact on your Back4App Database asynchronously, and passes a Result<Contact, ParseError> object to the completion block to handle the save process.
 newContact.save { result in
     // Handle the result to check wether the save process was successfull or not
 }
//When creating and saving a new instance of Contact we can use
 var newContact: Contact = Contact(name: "John Doe", birthday: Date(), numberOfFriends: 5, favoriteFoods: ["Bread", "Pizza"])
2
 // Saves newContact on your Back4App Database synchronously and returns the new saved Item. It throws and error if something went wrong.
 let savedContact = try? newContact.save()
5
 // Saves newContact on your Back4App Database asynchronously, and passes a Result<Contact, ParseError> object to the completion block to handle the save process.
 newContact.save { result in
     // Handle the result to check wether the save process was successfull or not
 }
﻿
- Download the Contacts App Template
The XCode project has the following structure
﻿
At any time, you can access the complete Project via our GitHub repositories.
﻿iOS Example Repository﻿
To focus on the main objective of this guide, we will only detail the sections strictly related to queries and the ParseSwift SDK.
- Additional CRUD flow
Before getting started with queries, it is necessary to have some contacts already saved on your Back4App Database. In the NewContactController class, we implement a basic form to add a Contact. To save an instance of a Contact object, we use the handleAddContact() method implemented in the NewContactController class
Swift
 // NewContactController.swift file
 ...
3
 extension NewContactController {
     /// Retrieves the info the user entered for a new contact and stores it on your Back4App Database
     @objc fileprivate func handleAddContact() {
         view.endEditing(true)
      
         // Collect the contact's information from the form
        guard let name = nameTextField.text,
              let numberOfFriendsString = numberOfFriendsTextField.text,
              let numberOfFriends = Int(numberOfFriendsString),
              let favoriteFoods = favoriteFoodsTextField.text?.split(separator: ",") else {
            return showAlert(title: "Error", message: "The data you entered is con valid.")
        }
      
        // Once the contact's information is collected, instantiate a Contact object to save it on your Back4App Database
        let contact = Contact(
            name: name,
            birthday: birthdayDatePicker.date,
            numberOfFriends: numberOfFriends,
            favoriteFoods: favoriteFoods.compactMap { String($0).trimmingCharacters(in: .whitespaces) }
        )
      
        // Save the new Contact
        contact.save { [weak self] result in
            switch result {
            case .success(_):
                self?.showAlert(title: "Success", message: "Contact saved.") {
                    self?.dismiss(animated: true, completion: nil)
                }
            case .failure(let error):
                self?.showAlert(title: "Error", message: "Failed to save contact: \(error.message)")
            }
        }
    }
}
 // NewContactController.swift file
 ...
3
 extension NewContactController {
     /// Retrieves the info the user entered for a new contact and stores it on your Back4App Database
     @objc fileprivate func handleAddContact() {
         view.endEditing(true)
      
         // Collect the contact's information from the form
        guard let name = nameTextField.text,
              let numberOfFriendsString = numberOfFriendsTextField.text,
              let numberOfFriends = Int(numberOfFriendsString),
              let favoriteFoods = favoriteFoodsTextField.text?.split(separator: ",") else {
            return showAlert(title: "Error", message: "The data you entered is con valid.")
        }
      
        // Once the contact's information is collected, instantiate a Contact object to save it on your Back4App Database
        let contact = Contact(
            name: name,
            birthday: birthdayDatePicker.date,
            numberOfFriends: numberOfFriends,
            favoriteFoods: favoriteFoods.compactMap { String($0).trimmingCharacters(in: .whitespaces) }
        )
      
        // Save the new Contact
        contact.save { [weak self] result in
            switch result {
            case .success(_):
                self?.showAlert(title: "Success", message: "Contact saved.") {
                    self?.dismiss(animated: true, completion: nil)
                }
            case .failure(let error):
                self?.showAlert(title: "Error", message: "Failed to save contact: \(error.message)")
            }
        }
    }
}
﻿
For more details about this step, you can go to the basic operations guide.
- Performing basic queries
- By name
The first example we look at is a query that allows us to retrieve contacts which have a specific substring in their name field. In order to do this, we first create a QueryConstraint object. This object will contain the constraint we want. The ParseSwift SDK provides the following methods to (indirectly) create a QueryConstraint﻿
Swift
 // QueryConstraint.swift file
2
 /**
   Add a constraint for finding string values that contain a provided substring.
   - warning: This will be slow for large datasets.
   - parameter key: The key that the string to match is stored in.
   - parameter substring: The substring that the value must contain.
   - parameter modifiers: Any of the following supported PCRE modifiers (defaults to nil):
     - `i` - Case insensitive search
    - `m` - Search across multiple lines of input
  - returns: The resulting `QueryConstraint`.
 */
public func containsString(key: String, substring: String, modifiers: String? = nil) -> QueryConstraint
14
/**
 Add a constraint that requires that a key is equal to a value.
 - parameter key: The key that the value is stored in.
 - parameter value: The value to compare.
 - returns: The same instance of `QueryConstraint` as the receiver.
 - warning: See `equalTo` for more information.
 Behavior changes based on `ParseSwift.configuration.isUsingEqualQueryConstraint`
 where isUsingEqualQueryConstraint == true is known not to work for LiveQuery on
 Parse Servers  <= 5.0.0.
 */
public func == <T>(key: String, value: T) -> QueryConstraint where T: Encodable
 // QueryConstraint.swift file
2
 /**
   Add a constraint for finding string values that contain a provided substring.
   - warning: This will be slow for large datasets.
   - parameter key: The key that the string to match is stored in.
   - parameter substring: The substring that the value must contain.
   - parameter modifiers: Any of the following supported PCRE modifiers (defaults to nil):
     - `i` - Case insensitive search
    - `m` - Search across multiple lines of input
  - returns: The resulting `QueryConstraint`.
 */
public func containsString(key: String, substring: String, modifiers: String? = nil) -> QueryConstraint
14
/**
 Add a constraint that requires that a key is equal to a value.
 - parameter key: The key that the value is stored in.
 - parameter value: The value to compare.
 - returns: The same instance of `QueryConstraint` as the receiver.
 - warning: See `equalTo` for more information.
 Behavior changes based on `ParseSwift.configuration.isUsingEqualQueryConstraint`
 where isUsingEqualQueryConstraint == true is known not to work for LiveQuery on
 Parse Servers  <= 5.0.0.
 */
public func == <T>(key: String, value: T) -> QueryConstraint where T: Encodable
﻿
For instance, a query that allows us to retrieve all the Contact’s with John in their name field can be created with
Swift
 // Create the query sending the constraint as parameter
 let constraint: QueryConstraint = containsString(key: "name", substring: "John") // The first parameter (key) referres to the name of the field
 let query = Contact.query(constrain)
4
 // Retrieve the contacts asynchronously (or sinchronously if needed)
 query.find() { result in
     // Handle the result and do the corresponding UI update
 }
 // Create the query sending the constraint as parameter
 let constraint: QueryConstraint = containsString(key: "name", substring: "John") // The first parameter (key) referres to the name of the field
 let query = Contact.query(constrain)
4
 // Retrieve the contacts asynchronously (or sinchronously if needed)
 query.find() { result in
     // Handle the result and do the corresponding UI update
 }
﻿
In case the constraint requires the name field to match exactly a given string, we can use
Swift
 // Create the query sending the constraint as parameter
 let value = "John"
 let constraint: QueryConstraint = "name" == value
 let query = Contact.query(constrain)
 // Create the query sending the constraint as parameter
 let value = "John"
 let constraint: QueryConstraint = "name" == value
 let query = Contact.query(constrain)
﻿
- By number of friends
A query with a constraint involving a numerical comparison can be constructed by creating aQueryConstraint with
Swift
 /**
  Add a constraint that requires that a key is greater than a value.
  - parameter key: The key that the value is stored in.
  - parameter value: The value to compare.
  - returns: The same instance of `QueryConstraint` as the receiver.
  */
 public func > <T>(key: String, value: T) -> QueryConstraint where T: Encodable
8
 /**
 Add a constraint that requires that a key is greater than or equal to a value.
 - parameter key: The key that the value is stored in.
 - parameter value: The value to compare.
 - returns: The same instance of `QueryConstraint` as the receiver.
 */
public func >= <T>(key: String, value: T) -> QueryConstraint where T: Encodable
16
/**
 Add a constraint that requires that a key is less than a value.
 - parameter key: The key that the value is stored in.
 - parameter value: The value to compare.
 - returns: The same instance of `QueryConstraint` as the receiver.
 */
public func < <T>(key: String, value: T) -> QueryConstraint where T: Encodable
24
/**
 Add a constraint that requires that a key is less than or equal to a value.
 - parameter key: The key that the value is stored in.
 - parameter value: The value to compare.
 - returns: The same instance of `QueryConstraint` as the receiver.
 */
public func <= <T>(key: String, value: T) -> QueryConstraint where T: Encodable

 /**
  Add a constraint that requires that a key is greater than a value.
  - parameter key: The key that the value is stored in.
  - parameter value: The value to compare.
  - returns: The same instance of `QueryConstraint` as the receiver.
  */
 public func > <T>(key: String, value: T) -> QueryConstraint where T: Encodable
8
 /**
 Add a constraint that requires that a key is greater than or equal to a value.
 - parameter key: The key that the value is stored in.
 - parameter value: The value to compare.
 - returns: The same instance of `QueryConstraint` as the receiver.
 */
public func >= <T>(key: String, value: T) -> QueryConstraint where T: Encodable
16
/**
 Add a constraint that requires that a key is less than a value.
 - parameter key: The key that the value is stored in.
 - parameter value: The value to compare.
 - returns: The same instance of `QueryConstraint` as the receiver.
 */
public func < <T>(key: String, value: T) -> QueryConstraint where T: Encodable
24
/**
 Add a constraint that requires that a key is less than or equal to a value.
 - parameter key: The key that the value is stored in.
 - parameter value: The value to compare.
 - returns: The same instance of `QueryConstraint` as the receiver.
 */
public func <= <T>(key: String, value: T) -> QueryConstraint where T: Encodable
﻿
To query all contacts with 30 or more friends, we use
Swift
 let query = Contacts.query("numberOfFriends" >= 30)
2
 // Retrieve the contacts asynchronously (or sinchronously if needed)
 query.find() { result in
     // Handle the result and do the corresponding UI update
 }
 let query = Contacts.query("numberOfFriends" >= 30)
2
 // Retrieve the contacts asynchronously (or sinchronously if needed)
 query.find() { result in
     // Handle the result and do the corresponding UI update
 }
﻿
- Ordering query results
For ordering the results from a query, the Query<contacts> object provides the method order(_:) which returns a new Query<contact> object considering the requested ordering option. As a parameter, we pass an enumeration (Query<contact>.Order) to indicate the ordering we want. The following snippet applies a descending order based on the birthday field
Swift
 // A query without order to retrieve all the Contact items
 let unorderedQuery = Contact.query()
3
 // Sorts the contacts based on their brithday. The parameter in the enumeration is the key of the field used to order the results
 let descendingOrder = Query<Contact>.Order.descending("birthday")
6
 let orderedQuery = unorderedQuery.order([descendingOrder]) // Returns a new query with the requested (descending) ordering option
8
 // Executes que query asynchronously and returns a Result<[Contact], ParseError> object with the result
orderedContacts.find() { result in
    // Handle the result
}
 // A query without order to retrieve all the Contact items
 let unorderedQuery = Contact.query()
3
 // Sorts the contacts based on their brithday. The parameter in the enumeration is the key of the field used to order the results
 let descendingOrder = Query<Contact>.Order.descending("birthday")
6
 let orderedQuery = unorderedQuery.order([descendingOrder]) // Returns a new query with the requested (descending) ordering option
8
 // Executes que query asynchronously and returns a Result<[Contact], ParseError> object with the result
orderedContacts.find() { result in
    // Handle the result
}
﻿
In the project example, we implemented the queries mentioned above. The ContactsController class has the method fetchContacts() where you will find the following snippet 
Swift
 ...
2
 class ContactsController {
     let queryType: QueryType
5
     ...
7
     private func fetchContacts() {
         // We create a Query<Contact> according to the queryType enumeration
        let query: Query<Contact> = {
            switch queryType {
            case .byName(let value):
                return Contact.query(containsString(key: "name", substring: value))
            case .byNumberOfFriends(let quantity):
                return Contact.query("numberOfFriends" >= quantity)
            case .byOrdering(let order):
                let query = Contact.query()
                switch order {
                case .ascending: return query.order([.ascending("birthday")])
                case .descending: return query.order([.descending("birthday")])
                }
            case .all:
                return Contact.query()
            }
        }()
      
        // Execute the query
        query.find { [weak self] result in
            switch result {
            case .success(let contacts):
                self?.contacts = contacts
              
                // Update the UI
                DispatchQueue.main.async { self?.tableView.reloadData() }
            case .failure(let error):
                // Notify the user about the error that happened during the fetching process
                self?.showAlert(title: "Error", message: "Failed to retrieve contacts: \(error.message)")
                return
            }
        }
    }
}
 ...
2
 class ContactsController {
     let queryType: QueryType
5
     ...
7
     private func fetchContacts() {
         // We create a Query<Contact> according to the queryType enumeration
        let query: Query<Contact> = {
            switch queryType {
            case .byName(let value):
                return Contact.query(containsString(key: "name", substring: value))
            case .byNumberOfFriends(let quantity):
                return Contact.query("numberOfFriends" >= quantity)
            case .byOrdering(let order):
                let query = Contact.query()
                switch order {
                case .ascending: return query.order([.ascending("birthday")])
                case .descending: return query.order([.descending("birthday")])
                }
            case .all:
                return Contact.query()
            }
        }()
      
        // Execute the query
        query.find { [weak self] result in
            switch result {
            case .success(let contacts):
                self?.contacts = contacts
              
                // Update the UI
                DispatchQueue.main.async { self?.tableView.reloadData() }
            case .failure(let error):
                // Notify the user about the error that happened during the fetching process
                self?.showAlert(title: "Error", message: "Failed to retrieve contacts: \(error.message)")
                return
            }
        }
    }
}
﻿
- Run the app!
Before pressing the run button on XCode, do not forget to configure your Back4App application in the AppDelegate class!
Using the+button in the navigation bar, add a counple of contacts and test the different queries.