Data Storage Guide for Swift
The LeanStorage Swift SDK can be used to persist and query data in LeanCloud. The code below shows how you can create an object and store it into the cloud:
do {
// Create an object
let todo = LCObject(className: "Todo")
// Set values of fields
try todo.set("title", value: "R&D Weekly Meeting")
try todo.set("content", value: "All team members, Tue 2pm")
// Save the object to the cloud
_ = todo.save { result in
switch result {
case .success:
// Execute any logic that should take place after the object is saved
break
case .failure(error: let error):
// Execute any logic that should take place if the save fails
print(error)
}
}
} catch {
print(error)
}
The SDK designed for each language interacts with the same REST API via HTTPS, offering fully functional interfaces for you to manipulate the data in the cloud.
Installing SDK
See Installing Swift SDK.
Objects
LCObject
The objects on the cloud are built around LCObject
. Each LCObject
contains key-value pairs of JSON-compatible data. This data is schema-free, which means that you don't need to specify ahead of time what keys exist on each LCObject
. Simply set whatever key-value pairs you want, and our backend will store them.
For example, the LCObject
storing a simple todo item may contain the following data:
title: "Email Linda to Confirm Appointment",
isComplete: false,
priority: 2,
tags: ["work", "sales"]
Data Types
LCObject
supports a wide range of data types to be used for each field, including common ones like String
, Number
, Boolean
, Object
, Array
, and Date
. You can nest objects in JSON format to store more structured data within a single Object
or Array
field.
Special data types supported by LCObject
include Pointer
and File
, which are used to store a reference to another LCObject
and binary data respectively.
LCObject
also supports GeoPoint
, a special data type you can use to store location-based data. See GeoPoints for more details.
Some examples:
let number : LCNumber = 42
let bool : LCBool = true
let string : LCString = "foo"
let dictionary : LCDictionary = LCDictionary(["name": string, "count": number])
let array : LCArray = LCArray([number, bool, string])
let data : LCData = LCData()
let date : LCDate = LCDate()
let null : LCNull = LCNull()
let geoPoint : LCGeoPoint = LCGeoPoint(latitude: 45, longitude: -45)
let acl : LCACL = LCACL()
let object : LCObject = LCObject()
let relation : LCRelation = object.relationForKey("elements")
let user : LCUser = LCUser()
let file : LCFile = LCFile()
let installation : LCInstallation = LCInstallation()
We do not recommend storing large pieces of binary data like images or documents with LCObject
using byte[]
. The size of each LCObject
should not exceed 128 KB. We recommend using LCFile
for storing images, documents, and other types of files. To do so, create LCFile
objects and assign them to fields of LCObject
. See Files for details.
Keep in mind that our backend stores dates in UTC format and the SDK will convert them to local times upon retrieval.
The date values displayed on Dashboard > Data Storage > Data are also converted to match your operating system's time zone. The only exception is that when you retrieve these date values through our REST API, they will remain in UTC format. You can manually convert them using appropriate time zones when necessary.
To learn about how you can protect the data stored on the cloud, see Data Security.
Creating Objects
The code below creates a new instance of LCObject
with class Todo
:
let todo = LCObject(className: "Todo")
The constructor takes a class name as a parameter so that the cloud knows the class you are using to create the object. A class is comparable to a table in a relational database. A class name starts with a letter and can only contain numbers, letters, and underscores.
Saving Objects
The following code saves a new object with class Todo
to the cloud:
do {
// Create an object
let todo = LCObject(className: "Todo")
// Set values of fields
try todo.set("title", value: "Sign up for Marathon")
try todo.set("priority", value: 2)
// Save the object to the cloud
_ = todo.save { result in
switch result {
case .success:
// Execute any logic that should take place after the object is saved
break
case .failure(error: let error):
// Execute any logic that should take place if the save fails
print(error)
}
}
} catch {
print(error)
}
To make sure the object is successfully saved, take a look at Dashboard > Data Storage > Data > Todo
in your app. You should see a new entry of data with something like this when you click on its objectId
:
{
"title": "Sign up for Marathon",
"priority": 2,
"ACL": {
"*": {
"read": true,
"write": true
}
},
"objectId": "582570f38ac247004f39c24b",
"createdAt": "2017-11-11T07:19:15.549Z",
"updatedAt": "2017-11-11T07:19:15.549Z"
}
You don't have to create or set up a new class called Todo
in Dashboard > Data Storage > Data before running the code above. If the class doesn't exist, it will be automatically created.
Several built-in fields are provided by default which you don't need to specify in your code:
Built-in Field | Type | Description |
---|---|---|
objectId | String | A unique identifier for each saved object. |
ACL | LCACL | Access Control List, a special object defining the read and write permissions of other people. |
createdAt | Date | The time the object was created. |
updatedAt | Date | The time the object was last modified. |
Each of these fields is filled in by the cloud automatically and doesn't exist on the local LCObject
until a save operation has been completed.
Field names, or keys, can only contain letters, numbers, and underscores. A custom key can neither start with double underscores __
, nor be identical to any system reserved words or built-in field names (ACL
, className
, createdAt
, objectId
, and updatedAt
) regardless of letter cases.
Values can be strings, numbers, booleans, or even arrays and dictionaries — anything that can be JSON-encoded. See Data Types for more information.
We recommend that you adopt CamelCase naming convention to NameYourClassesLikeThis
and nameYourKeysLikeThis
, which keeps your code more readable.
Retrieving Objects
If an LCObject
is already in the cloud, you can retrieve it using its objectId
with the following code:
let query = LCQuery(className: "Todo")
let _ = query.get("582570f38ac247004f39c24b") { (result) in
switch result {
case .success(object: let todo):
// todo is the instance of the Todo object with objectId 582570f38ac247004f39c24b
let title = todo.get("title")
let priority = todo.get("priority")
// Acquire special properties
let objectId = todo.objectId
let updatedAt = todo.updatedAt
let createdAt = todo.createdAt
case .failure(error: let error):
print(error)
}
}
If you try to access a field or property that doesn't exist, the SDK will not raise an error. Instead, it will return null
.
Sometimes you may want to get
all the fields back at one time without calling get on each field of the object. This could be helpful when you implement data binding. To do so, call toJSON
on LCObject
:
Refreshing Objects
If you need to refresh a local object with the latest version of it in the cloud, call the fetch
method on it:
let todo = LCObject(className: "Todo", objectId: "582570f38ac247004f39c24b")
_ = todo.fetch { result in
switch result {
case .success:
// todo is refreshed
break
case .failure(error: let error):
print(error)
}
}
Updating Objects
To update an existing object, assign the new data to each field and call the save
method. For example:
do {
let todo = LCObject(className: "Todo", objectId: "582570f38ac247004f39c24b")
try todo.set("content", value: "Weekly meeting has been rescheduled to Wed 3pm for this week.")
todo.save { (result) in
switch result {
case .success:
break
case .failure(error: let error):
print(error)
}
}
} catch {
print(error)
}
LeanCloud automatically figures out which data has changed and only the fields with changes will be sent to the cloud. The fields you didn't update will remain intact.
do {
let account = LCObject(className: "Account", objectId: "5745557f71cfe40068c6abe0")
// Atomically decrease balance by 100
let amount = -100
try account.increase("balance", by: amount)
// Add the condition
let query = LCQuery(className: "Account")
query.whereKey("balance", .greaterThanOrEqualTo(-amount))
let options: [LCObject.SaveOption] = [
.query(query),
// Return the latest data in the cloud upon completion.
// All the fields will be returned if the object is new,
// otherwise only fields with changes will be returned.
.fetchWhenSave
]
account.save(options: options) { (result) in
switch result {
case .success:
if let balance = account["balance"] {
print("Balance: \(balance)")
}
case .failure(error: let error):
if error.code == 305 {
print("Insufficient balance. Operation failed!")
}
}
}
} catch {
print(error)
}
Updating Counters
Take Twitter as an example, we need to keep track of how many Likes and Retweets a tweet has gained so far. Since a Like or Retweet action can be triggered simultaneously by multiple clients, saving objects with updated values directly can lead to inaccurate results. To make sure that the total number is stored correctly, you can atomically increase (or decrease) the value of a number field:
try post.increase("likes", by: 1)
You can specify the amount of increment (or decrement) by providing an additional argument. If the argument is not provided, 1
is used by default.
Updating Arrays
There are several operations that can be used to atomically update an array associated with a given key:
append(String, element: LCType)
appends the given object to the end of an array.append(String, element: LCType, unique: Bool)
appends the given object to the end of an array. A bool can be specified for unique to ensure that the object only appears once within the array.append(String, elements: [LCType])
appends the given array of objects to the end of an array.append(String, elements: [LCType], unique: Bool)
appends the given array of objects to the end of an array. A bool can be specified for unique to ensure that each object only appears once within the array.remove(String, element: LCType)
removes all instances of the given object from an array.remove(String, elements: [LCType])
removes all instances of the given array of objects from an array.
For example, Todo
has a field named alarms
for keeping track of the times at which a user wants to be alerted. The following code adds the times to the alarms field:
func dateWithString(_ string: String) -> LCDate {
let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
dateFormatter.locale = Locale(identifier: "en_US_POSIX")
let date = LCDate(dateFormatter.date(from: string)!)
return date
}
func testSetArray() {
do {
let todo = LCObject(className: "Todo")
let reminder1 = dateWithString("2018-04-30 07:10:00")
let reminder2 = dateWithString("2018-04-30 07:20:00")
try todo.set("reminders", value: [reminder1, reminder2])
let result = todo.save()
assert(result.isSuccess)
let reminder3 = dateWithString("2018-04-30 07:30:00")
try todo.append("reminders", element: reminder3, unique: true)
_ = todo.save { result in
switch result {
case .success:
break
case .failure(error: let error):
print(error)
}
}
} catch {
print(error)
}
}
Deleting Objects
The following code deletes a Todo
object from the cloud:
let todo = LCObject(className: "Todo", objectId: "582570f38ac247004f39c24b")
_ = todo.delete { result in
switch result {
case .success:
break
case .failure(error: let error):
print(error)
}
}
Removing data from the cloud should always be dealt with great caution as it may lead to non-recoverable data loss. We strongly advise that you read ACL Guide to understand the risks thoroughly. You should also consider implementing class-level, object-level, and field-level permissions for your classes in the cloud to guard against unauthorized data operations.
Batch Processing
You can create, save, delete, or fetch multiple objects within a single request:
// Create an array for storing LCObjects
let objects: [LCObject] = []
// Batch create and update
_ = LCObject.save(objects, completion: { (result) in
switch result {
case .success:
break
case .failure(error: let error):
print(error)
}
})
// Batch delete
_ = LCObject.delete(objects, completion: { (result) in
switch result {
case .success:
break
case .failure(error: let error):
print(error)
}
})
// Batch fetch
_ = LCObject.fetch(objects, completion: { (result) in
switch result {
case .success:
break
case .failure(error: let error):
print(error)
}
})
The following code sets isComplete
of all Todo
objects to be true
:
let query = LCQuery(className: "Todo")
_ = query.find { (result) in
switch result {
case .success(objects: let todos):
// Get a collection of todos to work on
for todo in todos {
do {
// Update value
try todo.set("isComplete", value: true)
} catch {
print(error)
}
}
// Save all at once
let _ = LCObject.save(todos, completion: { (result) in
switch result {
case .success:
break
case .failure(error: let error):
print(error)
}
})
case .failure(error: let error):
print(error)
}
}
Although each function call sends multiple operations in one single network request, saving operations and fetching operations are billed as separate API calls for each object in the collection, while deleting operations are billed as a single API call.
Data Models
Objects may have relationships with other objects. For example, in a blogging application, a Post
object may have relationships with many Comment
objects. The Data Storage service supports three kinds of relationships, including one-to-one, one-to-many, and many-to-many.
One-to-One and One-to-Many Relationships
One-to-one and one-to-many relationships are modeled by saving LCObject
as a value in the other object. For example, each Comment
in a blogging app might correspond to one Post
.
The following code creates a new Post
with a single Comment
:
do {
// Create a post
let post = LCObject(className: "Post")
try post.set("title", value: "I am starving!")
try post.set("content", value: "Hmmm, where should I go for lunch?")
// Create a comment
let comment = LCObject(className: "Comment")
try comment.set("content", value: "KFC is the best!")
// Add the post as a property of the comment
try comment.set("parent", value: post)
// This will save both post and comment
assert(comment.save().isSuccess)
} catch {
print(error)
}
Internally, the backend will store the referred-to object with the Pointer
type in just one place in order to maintain consistency. You can also link objects using their objectId
s like this:
let post = LCObject(className: "Post", objectId: "57328ca079bc44005c2472d0")
try comment.set("post", value: post)
See Relational Queries for instructions on how to query relational data.
Many-to-Many Relationships
The easiest way to model many-to-many relationships is to use arrays. In most cases, using arrays helps you reduce the number of queries you need to make and leads to better performance. However, if additional properties need to be attached to the relationships between two classes, using join tables would be a better choice. Keep in mind that the additional properties are used to describe the relationships between classes rather than any single class.
We recommend you to use join tables if the total number of objects of any class exceeds 100.
Queries
We've already seen how you can retrieve a single object from the cloud with LCObject
, but it doesn't seem to be powerful enough when you need to retrieve multiple objects that match certain conditions at once. In such a situation, LCQuery
would be a more efficient tool you can use.
Basic Queries
The general steps of performing a basic query include:
- Creating
LCQuery
. - Putting conditions on it.
- Retrieving an array of objects matching the conditions.
The code below retrieves all Student
objects whose lastName
is Smith
:
let query = LCQuery(className: "Student")
query.whereKey("lastName", .equalTo("Smith"))
_ = query.find { result in
switch result {
case .success(objects: let students):
// students is an array of Student objects satisfying conditions
break
case .failure(error: let error):
print(error)
}
}
Query Constraints
There are several ways to put constraints on the objects found by LCObject
.
The code below filters out objects with Jack
as firstName
:
query.whereKey("firstName", .notEqualTo("Jack"))
For sortable types like numbers and strings, you can use comparisons in queries:
// Restricts to age < 18
query.whereKey("age", .lessThan(18));
// Restricts to age <= 18
query.whereKey("age", .lessThanOrEqualTo(18));
// Restricts to age > 18
query.whereKey("age", .greaterThan(18));
// Restricts to age >= 18
query.whereKey("age", .greaterThanOrEqualTo(18));
You can apply multiple constraints to a single query, and objects will only be in the results if they match all of the constraints. In other words, it's like concatenating constraints with AND
:
query.whereKey("firstName", .equalTo("Jack"))
query.whereKey("age", .greaterThan(18))
You can limit the number of results by setting limit
(defaults to 100
):
// Limit to at most 10 results
query.limit = 10
For performance reasons, the maximum value allowed for limit
is 1000
, meaning that the cloud would only return 1,000 results even if it is set to be greater than 1000
.
If you need exactly one result, you may use first
for convenience:
let query = LCQuery(className: "Todo")
query.whereKey("priority", .equalTo(2))
_ = query.getFirst { result in
switch result {
case .success(object: let todo):
print(todo)
case .failure(error: let error):
print(error)
}
}
You can skip a certain number of results by setting skip
:
// Skip the first 20 results
query.skip = 20
You can implement pagination in your app by using skip
together with limit
:
let query = LCQuery(className: "Todo")
query.whereKey("priority", .equalTo(2))
query.limit = 10
query.skip = 20
Keep in mind that the higher the skip
goes, the slower the query will run. You may consider using createdAt
or updatedAt
(which are indexed) to set range boundaries for large datasets to make queries more efficient.
You may also use the last value returned from an auto-increment field along with limit
for pagination.
For sortable types, you can control the order in which results are returned:
// Sorts the results in ascending order by the createdAt property
query.whereKey("createdAt", .ascending)
// Sorts the results in descending order by the createdAt property
query.whereKey("createdAt", .descending)
You can even attach multiple sorting rules to a single query:
query.whereKey("priority", .ascending)
query.whereKey("createdAt", .descending)
To retrieve objects that have or do not have particular fields:
// Finds objects that have the "images" field
query.whereKey("images", .existed)
// Finds objects that don't have the "images" field
query.whereKey("images", .notExisted)
You can restrict the fields returned by providing a list of keys with selectKeys
. The code below retrieves todos with only the title
and content
fields (and also special built-in fields including objectId
, createdAt
, and updatedAt
):
let query = LCQuery(className: "Todo")
query.whereKey("title", .selected)
query.whereKey("content", .selected)
_ = query.getFirst { result in
switch result {
case .success(object: let todo):
let title = todo.get("title") // √
let content = todo.get("content") // √
let notes = todo.get("notes") // nil
case .failure(error: let error):
print(error)
}
}
You can add a minus prefix to the attribute name for inverted selection.
For example, if you do not care about the post author, use -author
.
The inverted selection also applies to preserved attributes and can be used with dot notations, e.g., -pubUser.createdAt
.
The unselected fields can be fetched later with fetchInBackground
. See Refreshing Objects.
Queries on String Values
Use .prefixedBy
to restrict to string values that start with a particular string. Similar to a LIKE
operator in SQL, it is indexed so it is efficient for large datasets:
let query = LCQuery(className: "Todo")
// SQL equivalent: title LIKE 'lunch%'
query.whereKey("title", .prefixedBy("lunch"))
Use .matchedSubstring
to restrict to string values that contain a particular string:
let query = LCQuery(className: "Todo")
// SQL equivalent: title LIKE '%lunch%'
query.whereKey("title", .matchedSubstring("lunch"))
Unlike .prefixedBy
, .matchedSubstring
can't take advantage of indexes, so it is not encouraged to be used for large datasets.
Please note that both .prefixedBy
and .matchedSubstring
perform case-sensitive matching, so the examples above will not look for string values containing Lunch
, LUNCH
, etc.
If you are looking for string values that do not contain a particular string, use .matchedPattern
with regular expressions:
let query = LCQuery(className: "Todo")
// "title" without "ticket" (case-insensitive)
query.whereKey("title", .matchedRegularExpression("^((?!ticket).)*$", option: "i"))
However, performing queries with regular expressions as constraints can be very expensive, especially for classes with over 100,000 records. The reason behind this is that queries like this can't take advantage of indexes and will lead to exhaustive scanning of the whole dataset to find the matching objects. We recommend that you take a look at our In-App Searching feature, a full-text search solution we provide to improve your app's searching ability and user experience.
If you are facing performance issues with queries, please refer to Optimizing Performance for possible workarounds and best practices.
Queries on Array Values
The code below looks for all the objects with work
as an element of its array field tags
:
query.whereKey("tags", .equalTo("work"))
To look for objects whose array field tags
contains three elements:
query.whereKey("tags", .equalToSize(3))
You can also look for objects whose array field tags
contains work
, sales
, and appointment
:
query.whereKey("tags", .containedAllIn(["work", "sales", "appointment"]))
To retrieve objects whose field matches any one of the values in a given list, you can use .containedIn
instead of performing multiple queries. The code below constructs a query that retrieves todo items with priority
to be 1
or 2
:
// Single query
let priorityOneOrTwo = LCQuery(className: "Todo")
priorityOneOrTwo.whereKey("priority", .containedIn([1, 2]))
// Mission completed :)
// ---------------
// vs.
// ---------------
// Multiple queries
let priorityOne = LCQuery(className: "Todo")
priorityOne.whereKey("priority", .equalTo(1))
let priorityTwo = LCQuery(className: "Todo")
priorityTwo.whereKey("priority", .equalTo(2))
let priorityOneOrTwo = priorityOne.or(priorityTwo)
// Kind of verbose :(
Conversely, you can use .notContainedIn
if you want to retrieve objects that do not match any of the values in a list.
Relational Queries
There are several ways to perform queries for relational data. To retrieve objects whose given field matches a particular LCObject
, you can use .equalTo
just like how you use it for other data types. For example, if each Comment
has a Post
object in its post
field, you can fetch all the comments for a particular Post
with the following code:
let post = LCObject(className: "Post", objectId: "57328ca079bc44005c2472d0")
let query = LCQuery(className: "Comment")
query.whereKey("post", .equalTo(post))
_ = query.find { result in
switch result {
case .success(objects: let comments):
// comments contains the comments for the post
break
case .failure(error: let error):
print(error)
}
}
To retrieve objects whose given field contains an LCObject
that matches a different query, you can use .matchedQuery
. The code below constructs a query that looks for all the comments for posts with images:
let innerQuery = LCQuery(className: "Post")
innerQuery.whereKey("image", .existed)
let query = LCQuery(className: "Comment")
query.whereKey("post", .matchedQuery(innerQuery))
To retrieve objects whose given field does not contain an LCObject
that matches a different query, use .notMatchedQuery
instead.
Sometimes you may need to look for related objects from different classes without extra queries. In such situations, you can use .included
on the same query. The following code retrieves the last 10 comments together with the posts related to them:
let query = LCQuery(className: "Comment")
// Retrieve the most recent ones
query.whereKey("createdAt", .descending)
// Only retrieve the last 10
query.limit = 10
// Include the related post together with each comment
query.whereKey("post", .included)
_ = query.find { result in
switch result {
case .success(objects: let comments):
// comments contains the last 10 comments including the post associated with each
for comment in comments {
// This does not require a network access
let post = comment.get("post") as? LCObject
}
case .failure(error: let error):
print(error)
}
}
You can even indicate multi-level associations using dot notations. If you wanted to include the post for each comment as well as the author of the post, you can do:
query.whereKey("post.author", .included)
Feel free to use .included
as many times as you need for the same query to have multiple fields included. Related objects retrieved in this way also works with LCQuery
helpers like getFirst
and get
.
Multi-level conditions passed into .included
won't work with any LCObject
contained in an array field. The furthest level that can be reached is the field itself.
You can also use dot notations with .selected
to limit the fields returned from the related objects:
query.whereKey("post.author.firstName", .selected)
Caveats about Inner Queries
The Data Storage service is not built on relational databases, which makes it impossible to join tables while querying. For the relational queries mentioned above, what we would do is to perform an inner query first (with 100
as the default limit
and 1000
as the maximum) and then insert the result from this query into the outer query. If the number of records matching the inner query exceeds the limit
and the outer query contains other constraints, the amount of the records returned in the end could be zero or less than your expectation since only the records within the limit
would be inserted into the outer query.
The following actions can be taken to solve the problem:
- Make sure the number of records in the result of the inner query is no more than 100. If it is between 100 and 1,000, set
1000
as thelimit
of the inner query. - Create redundancy for the fields being queried by the inner query on the table for the outer query.
- Repeat the same query with different
skip
values until all the records are gone through (performance issue could occur if the value ofskip
gets too big).
Counting Objects
If you just need to count how many objects match a query but do not need to retrieve the actual objects, use count
instead of find
. For example, to count how many todos have been completed:
let query = LCQuery(className: "Todo")
query.whereKey("isComplete", .equalTo(true))
let count = query.count()
Compound Queries
Compound queries can be used if complex query conditions need to be specified. A compound query is a logical combination (OR
or AND
) of subqueries.
Note that we do not support GeoPoint
or non-filtering constraints (e.g. near
, withinGeoBox
, limit
, skip
, ascending
, descending
, include
) in the subqueries of a compound query.
OR-ed Query Constraints
An object will be returned as long as it fulfills any one of the subqueries. The code below constructs a query that looks for all the todos that either have priorities higher than or equal to 3
, or are already completed:
let priorityQuery = LCQuery(className: "Todo")
priorityQuery.whereKey("priority", .greaterThanOrEqualTo(3))
let isCompleteQuery = LCQuery(className: "Todo")
isCompleteQuery.whereKey("isComplete", .equalTo(true))
let query = priorityQuery.or(isCompleteQuery)
Queries regarding GeoPoint
cannot be present among OR-ed queries.
AND-ed Query Constraints
The effect of using AND-ed query is the same as adding constraints to LCQuery
. The code below constructs a query that looks for all the todos that are created between 2016-11-13
and 2016-12-02
:
let dateFromString: (String) -> Date? = { string in
let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "yyyy-MM-dd"
return dateFormatter.date(from: string)
}
let startDateQuery = LCQuery(className: "Todo")
startDateQuery.whereKey("createdAt", .greaterThanOrEqualTo(dateFromString("2016-11-13")))
let endDateQuery = LCQuery(className: "Todo")
endDateQuery.whereKey("createdAt", .lessThan(dateFromString("2016-12-03")))
let query = startDateQuery.and(endDateQuery)
While using an AND-ed query by itself doesn't bring anything new compared to a basic query, to combine two or more OR-ed queries, you have to use AND-ed queries:
let dateFromString: (String) -> Date? = { string in
let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "yyyy-MM-dd"
return dateFormatter.date(from: string)
}
let createdAtQuery = LCQuery(className: "Todo")
createdAtQuery.whereKey("createdAt", .greaterThanOrEqualTo(dateFromString("2018-04-30")))
createdAtQuery.whereKey("createdAt", .lessThan(dateFromString("2018-05-01")))
let locationQuery = LCQuery(className: "Todo")
locationQuery.whereKey("location", .notExisted)
let priority2Query = LCQuery(className: "Todo")
priority2Query.whereKey("priority", .equalTo(2))
let priority3Query = LCQuery(className: "Todo")
priority3Query.whereKey("priority", .equalTo(3))
let priorityQuery = priority2Query.or(priority3Query)
let timeLocationQuery = locationQuery.or(createdAtQuery)
let query = priorityQuery.and(timeLocationQuery)
Optimizing Performance
There are several factors that could lead to potential performance issues when you conduct a query, especially when more than 100,000 records are returned at a time. We are listing some common ones here so you can design your apps accordingly to avoid them:
- Querying with "not equal to" or "not include" (index will not work)
- Querying on strings with a wildcard at the beginning of the pattern (index will not work)
- Using
count
with conditions (all the entries will be gone through) - Using
skip
for a large number of entries (all the entries that need to be skipped will be gone through) - Sorting without an index (querying and sorting cannot share a composite index unless the conditions used on them are both covered by the same one)
- Querying without an index (the conditions used on the query cannot share a composite index unless all of them are covered by the same one; additional time will be consumed if excessive data falls under the uncovered conditions)
Files
LCFile
allows you to store application files in the cloud that would otherwise be too large or cumbersome to fit into a regular LCObject
. The most common use case is storing images, but you can also use it for documents, videos, music, and any other binary data.
Creating Files
You can create a file from a string:
if let data = "LeanCloud".data(using: .utf8) {
let file = LCFile(payload: .data(data: data))
}
You can also create a file from a URL:
if let url = URL(string: "https://leancloud.cn/assets/imgs/press/Logo%20-%20Blue%20Padding.a60eb2fa.png") {
let file = LCFile(url: url)
}
When creating files from URLs, the SDK will not upload the actual files into the cloud but will store the addresses of the files as strings. This will not lead to actual traffic for uploading files, as opposed to creating files in other ways by doing which the files will be actually stored into the cloud.
LeanCloud will auto-detect the type of the file you are uploading based on the file extension, but you can also specify the Content-Type
(commonly referred to as MIME type):
if let data = "{\"company\":\"LeanCloud\"}".data(using: .utf8) {
let file = LCFile(payload: .data(data: data))
file.mimeType = "application/json"
}
But the most common method for creating files is to upload them from local paths:
if let url = Bundle.main.url(forResource: "avatar", withExtension: "jpg") {
let file = LCFile(payload: .fileURL(fileURL: url))
}
The file we uploaded here is named avatar.jpg
. There are a couple of things to note here:
- Each file uploaded will get its unique
objectId
, so it is allowed for multiple files to share the same name. - A correct extension needs to be assigned to each file which the cloud will use to infer the type of a file. For example, if you are storing a PNG image with
LCFile
, use.png
as its extension. - If the file doesn't have an extension and the content type is not specified, LeanCloud defaults the file's type to be
application/octet-stream
.
Saving Files
By saving a file, you store it into the cloud and get a permanent URL pointing to it:
_ = file.save { result in
switch result {
case .success:
if let value = file.objectId?.value {
print("File uploaded. objectId: " + value)
}
case .failure(error: let error):
// The file either could not be read or could not be saved to LeanCloud
print(error)
}
}
A file successfully uploaded can be found in Dashboard > Data Storage > Files and cannot be modified later. If you need to change the file, you have to upload the modified file again and a new objectId
and URL will be generated.
You can associate a file with LCObject
after it has been saved:
let todo = LCObject(className: "Todo")
todo.set("title", value: "Get Cakes")
// attachments is an Array field
todo.append("attachments", element: file)
todo.save()
You can also construct an LCQuery
to query files:
let query = LCQuery(className: "_File")
Note that the url
field of internal files (files uploaded to the file service) is dynamically generated by the cloud, which will switch custom domain names automatically.
Therefore, querying files by the url
field is only applicable to external files (files created by saving the external URL directly to the _File
table).
Query internal files by the key
field (path in URL) instead.
Upload Progress
You can monitor the upload progress and display that to the user:
_ = file.save(progress: { (progress) in
print(progress)
}) { (result) in
switch result {
case .success:
// Things to do after saving
break
case .failure(error: let error):
print(error)
}
}
File Metadata
When uploading a file, you can attach additional properties to it with metaData
. A file's metaData
cannot be updated once the file is stored to the cloud.
// Set metadata
file.metaData["author"] = "LeanCloud"
_ = file.save { result in
switch result {
case .success:
// Get author
String? author = file.metaData["author"]
// Get file name
String? fileName = file.name
// Get size (not available for files created from base64-encoded strings or URLs)
UInt64? size = file.metaData["size"]
case .failure(error: let error):
print(error)
}
}
Deleting Files
The code below deletes a file from the cloud:
let file = LCObject(className: "_File", objectId: "552e0a27e4b0643b709e891e")
file.delete()
By default, a file is not allowed to be deleted. We recommend you delete files by accessing our REST API with the Master Key. You can also allow certain users and roles to delete files by going to Dashboard > Data Storage > Files > Permission and select Others > Permission settings > delete..
GeoPoints
You can associate real-world latitude and longitude coordinates with an object by adding an LCGeoPoint
to the LCObject
. By doing so, queries on the proximity of an object to a given point can be performed, allowing you to implement functions like looking for users or places nearby easily.
To associate a point with an object, you need to create the point first. The code below creates an LCGeoPoint
with 39.9
as latitude
and 116.4
as longitude
:
let point = LCGeoPoint(latitude: 39.9, longitude: 116.4)
Now you can store the point into an object as a regular field:
try todo.set("location", value: point)
Geo Queries
With a number of existing objects with spatial coordinates, you can find out which of them are closest to a given point, or are contained within a particular area. This can be done by adding another restriction to LCQuery
using .locatedNear
. The code below returns a list of Todo
objects with location
closest to a given point:
let query = LCQuery(className: "Todo")
let point = LCGeoPoint(latitude: 39.9, longitude: 116.4)
query.whereKey("location", .locatedNear(point))
// Limit to 10 results
query.limit = 10
_ = query.find { result in
switch result {
case .success(objects: let todos):
// todos is an array of Todo objects satisfying conditions
break
case .failure(error: let error):
print(error)
}
}
Additional sorting conditions like .ascending
and .descending
will gain higher priorities than the default order by distance.
To have the results limited within a certain distance, check out .locatedNear's from
, and to parameters
in our API docs.
You can also query for the set of objects that are contained within a rectangular bounding box with .locatedWithin
:
let query = LCQuery(className: "Todo")
let southwest = LCGeoPoint(latitude: 30, longitude: 115)
let northeast = LCGeoPoint(latitude: 40, longitude: 118)
query.whereKey("location", .locatedWithin(southwest: southwest, northeast: northeast))
Caveats about GeoPoints
Points should not exceed the extreme ends of the ranges. Latitude should be between -90.0
and 90.0
. Longitude should be between -180.0
and 180.0
. Attempting to set latitude or longitude out of bounds will cause an error.
Also, each LCObject
can only have one field for LCGeoPoint
.
Users
Roles
As your app grows in scope and user base, you may find yourself needing more coarse-grained control over access to pieces of your data than user-linked ACLs can provide. To address this requirement, we support a form of role-based access control. Check the detailed ACL Guide to learn how to set it up for your objects.
Full-Text Search
Full-Text Search offers a better way to search through the information contained within your app. It's built with search engine capabilities that you can easily tap into your app. Effective and useful searching functionality in your app is crucial for helping users find what they need. For more details, see Full-Text Search Guide.