Thank you for choosing LeanCloud. We offer a collection of SDKs that help you build and publish an entire website or application without implementing the backend by yourself.
The Problem We're Solving
Most Internet-based applications are data-driven and share a very similar architecture:
The frontend presents the UI with data and handles interactions with the user while exchanging data with the app server on the backend.
The app server handles the main logic of the application by either generating data and storing it to the data server or gathering data from the data server and sending it to the frontend.
The data server stores the data and makes backups of it.
The model mentioned above works for most of the applications we see today. Although these applications share a variety of data structures and logic, they all have data flowing behind the scenes, which drives their functions. They also share a very similar backend framework (like LAMP). However, developers have been building the same system again and again, which tremendously increased the time and cost needed before they could launch their applications.
Our Solution
LeanCloud combines the most commonly used backend functions into a BaaS (Backend as a Service) consisting of the following parts:
Object-Oriented Data Storage The data transmitted between the frontend and the backend can be abstracted into objects regardless of the size or meaning of it. With LeanCloud, you can store any type of object and freely create, read, update, or delete them. We automatically handle the scaling of your app's database, so you don't have to worry about the size of your data or the amount of traffic produced by your application.
Large File Distribution No matter if you are building a website, an application, or a game, you would have plenty of static files that you need to store and distribute. Comparing to the data generated by your application, these files have larger sizes and often rely on CDN for faster delivery. LeanCloud provides full support for the storage and distribution of such files.
LeanEngine for Custom Server-Side Logic If the existing API cannot fulfill your requirements, you can define your server-side logic with LeanEngine. Similar to Google App Engine, LeanEngine allows you to build custom logic for your application with few lines of code. The code will be deployed to the cloud and works together with other services provided by LeanCloud.
Offline Data Analysis (for Business and Enterprise Plans) After launching your application for a while, you may want to look into the data generated by your users and see if any patterns can be found. With our offline data analysis platform, you can quickly process and analyse the data behind your application. The platform is totally distributed and realtime with its efficiency and scalability way higher than Hadoop MapReduce.
Below you will learn about the core concepts used by our storage system.
AVObject
As mentioned earlier, the data transmitted between clients and servers are abstracted into objects. An object stored on LeanCloud is called an "AVObject". Each AVObject has a class name and holds data in key-value pairs that are JSON-compatible. LeanCloud doesn't limit the number of keys allowed in each AVObject, nor does it require each AVObject to contain all the keys defined. To illustrate, imagine that we have a game that needs to store the following types of data:
User-related data, including usernames, passwords, and genders.
Score-related data, including players, scores, modes, and scenes.
We can store all these data with a single type of AVObject (suppose the class name to be AllInOne):
// User-related data, including username, password, and gender
{ "username": "steve", "password": "xxxxxx", "gender": "Male" }
// Score-related data, including player, score, mode, and scene
{ "playerName": "steve", "score": 1337, "cheatMode": false, "scene": 4 }
It's allowed that you store these two pieces of information with the same type of AVObject. However, we strongly recommend that you assign AVObjects with different purposes to different classes. For the example above, we can have a User class for all user-related data and a GameScore class for all score-related data.
AVObjects are categorized into tables according to their types (we use "table" here to help you better understand the concept; AVObjects are actually categorized based on the classes they fall into). AVObjects with the same class can be found in the same table. Each time when an AVObjects is saved to the cloud, a unique objectId will be assigned to it which is comparable to the primary key of a relational database. createdAt and updatedAt will also be filled in by the cloud which indicate the time the object is created and updated.
There are some differences between LeanCloud and traditional relational databases:
LeanCloud doesn't require interfaces like JDBC or ODBC for building connections. Instead, it directly exchanges JSON objects with clients via HTTP. By doing so, clients can access the data stored in the cloud without any additional backend servers. We offer native SDKs for multiple platforms (Objective-C, JavaScript, Python, PHP, Java, Swift, and other ones made by our community) that help you easily use our services with the language you are familiar with. We also offer REST API for you to use directly.
LeanCloud accepts all kinds of objects that are JSON-compatible. You can add new keys to a class whenever you want without defining table structures in advance.
LeanCloud adopts a new way to build relationships between AVObjects that doesn't involve primary keys or foreign keys. There is also no joining tables when performing queries. See Data Relationships for more details.
LeanCloud adopts a way that's different from SQL for querying AVObjects. See AVQuery for more details.
Data Types Supported
The keys in an AVObject can only contain letters, numbers, and underscores. A custom key cannot start with __ (double underscores). The values in an AVObject can be strings, numbers, booleans, arrays, or dictionaries. LeanCloud stores data in the format of JSON, so any objects that can be converted into JSON can be stored on LeanCloud. Besides the basic types, LeanCloud can also handle dates, Bytes, and files. To summarize, the types allowed in an AVObject include:
String
Number
Boolean
Array
Object
Date
Bytes (base64-encoded binary data)
File
Null (see notes below)
You cannot set a field to null via SDKs. It is not recommended to set a field to null via REST API.
You can leave the field unset instead.
An Object can contain key-value pairs with each value to be a JSON-compatible object. Keep in mind that the key of an Object cannot be __type or contain $ or . since they are reserved for special purposes. ACL, className, createdAt, objectId, and updatedAt are also reserved fields and cannot be used as custom keys.
Our SDKs can handle certain conversions between native types (for Objective-C and Java) and JSON. For example, when you are saving an NSString, it will be automatically converted to a String.
There are two ways to store binary data. When storing small pieces of data, you can use Bytes which allows you to write NSData or bytes[] directly into an AVObject. When storing actual files (like images, videos, and documents), you can store them as AVFiles with File and link them to existing AVObjects.
Data Type Solidification
When a class is first created, it does not contain a predefined schema. Therefore, for the first object being saved with it, the fields of it can hold any types of values that are supported.
However, when a field is saved for at least one time, the type of data it can accept will be restricted to those saved in the past. For example, if a User object is saved with its name to be a String, then all the User objects saved after that must have their name to be String (SDK will return an error if you attempt to save other types of data).
One exception is that all the fields can accept null regardless of their types. Keep in mind that if a field is saved for the first time with null as its value, the type of this field will be locked to Object. This may lead to unexpected outcomes in some instances. For example, if a User object has a field nickname and the first user being created doesn't set a nickname, then if the user is saved with nickname to be null, the type of nickname will be locked to Object. If this user or another user ever set a string for this field, an error will be thrown. Therefore, it is discouraged that you set null as the value of a field. If a field doesn't have a value, you may simply skip setting a value for the field. In Java SDK, the operation of setting null as a value will be ignored, which means that put(key, null) will not trigger any effect.
Once the type of a field is solidified, it cannot be changed unless you delete and recreate that field. For example, if there is a String field indexId holding numbers as strings and you need to change its type to Number, you may create a temporary field, copy the original data into there, delete the existing indexId, and copy the data back from the temporary field.
Data Management
You can manage the data in your application by going to Dashboard > LeanStorage > Data in your browser. This web console shows all the objects stored in your application in JSON.
Keep in mind that:
Entering null as a value will set the value to be the empty value null rather than the string "null".
objectId, createdAt, and updatedAt are set by the system automatically and cannot be edited.
Classes starting with an underscore are the built-in classes that cannot be deleted. You are not supposed to edit the default fields in them, but you can always add new fields.
Data Relationships
As mentioned earlier, LeanCloud doesn't use primary keys or foreign keys to build relationships between AVObjects. The following entities are used instead:
Pointer You can store the pointer to an object as a property of another project. This is often used for one-to-one and one-to-many relationships.
Array You can store an array of pointers as a property of another project. This is often used for one-to-many and many-to-many relationships.
Associative table You can create a class that links objects from other classes and attach additional information for each relationship. For example, when building a social network, you can have two fields of this class for followers and followees and have a third field for the times the relationships are formed.
Since LeanCloud adopts a data model that's different from those of relational databases, AVQuery is used in place of SQL for querying data. With AVQuery, you can:
Query a single object or multiple objects;
Apply constraints to queries;
Implement pagination;
Perform inner queries;
Cache query results so that history data is available even there's no Internet connectivity.
AVFile
Besides basic types of data, files like images, videos, and documents, as well as binary data, can also be stored on LeanCloud. Since data larger than 128 KB cannot be written into an AVObject, AVFile becomes a better carrier for it. AVFile also works with CDN so that files in your app can be delivered faster to the users. You can access AVFiles with either a shared domain or your own domains (recommended). Both HTTP and HTTPS are supported.
AVUser
Almost all apps need a user system to store information related to users. With AVUser, you can quickly implement functions like signing up with email or phone number and logging in with phone verification code.
A user can sign up or log in with the following methods:
Username (alphanumeric) + password
Email + password
Phone number + password
Phone number + verification code (if already signed up, then log in; if not, create a new account and log in)
OAuth (Facebook, Google, etc.)
A user can also reset their password with email or phone number. See the guides of each SDK for more details.
LeanStorage Overview
Thank you for choosing LeanCloud. We offer a collection of SDKs that help you build and publish an entire website or application without implementing the backend by yourself.
The Problem We're Solving
Most Internet-based applications are data-driven and share a very similar architecture:
The model mentioned above works for most of the applications we see today. Although these applications share a variety of data structures and logic, they all have data flowing behind the scenes, which drives their functions. They also share a very similar backend framework (like LAMP). However, developers have been building the same system again and again, which tremendously increased the time and cost needed before they could launch their applications.
Our Solution
LeanCloud combines the most commonly used backend functions into a BaaS (Backend as a Service) consisting of the following parts:
Object-Oriented Data Storage
The data transmitted between the frontend and the backend can be abstracted into objects regardless of the size or meaning of it. With LeanCloud, you can store any type of object and freely create, read, update, or delete them. We automatically handle the scaling of your app's database, so you don't have to worry about the size of your data or the amount of traffic produced by your application.
Large File Distribution
No matter if you are building a website, an application, or a game, you would have plenty of static files that you need to store and distribute. Comparing to the data generated by your application, these files have larger sizes and often rely on CDN for faster delivery. LeanCloud provides full support for the storage and distribution of such files.
LeanEngine for Custom Server-Side Logic
If the existing API cannot fulfill your requirements, you can define your server-side logic with LeanEngine. Similar to Google App Engine, LeanEngine allows you to build custom logic for your application with few lines of code. The code will be deployed to the cloud and works together with other services provided by LeanCloud.
Offline Data Analysis (for Business and Enterprise Plans)
After launching your application for a while, you may want to look into the data generated by your users and see if any patterns can be found. With our offline data analysis platform, you can quickly process and analyse the data behind your application. The platform is totally distributed and realtime with its efficiency and scalability way higher than Hadoop MapReduce.
Below you will learn about the core concepts used by our storage system.
AVObject
As mentioned earlier, the data transmitted between clients and servers are abstracted into objects. An object stored on LeanCloud is called an "AVObject". Each AVObject has a class name and holds data in key-value pairs that are JSON-compatible. LeanCloud doesn't limit the number of keys allowed in each AVObject, nor does it require each AVObject to contain all the keys defined. To illustrate, imagine that we have a game that needs to store the following types of data:
We can store all these data with a single type of AVObject (suppose the class name to be
AllInOne):It's allowed that you store these two pieces of information with the same type of AVObject. However, we strongly recommend that you assign AVObjects with different purposes to different classes. For the example above, we can have a
Userclass for all user-related data and aGameScoreclass for all score-related data.AVObjects are categorized into tables according to their types (we use "table" here to help you better understand the concept; AVObjects are actually categorized based on the classes they fall into). AVObjects with the same class can be found in the same table. Each time when an AVObjects is saved to the cloud, a unique
objectIdwill be assigned to it which is comparable to the primary key of a relational database.createdAtandupdatedAtwill also be filled in by the cloud which indicate the time the object is created and updated.There are some differences between LeanCloud and traditional relational databases:
Data Types Supported
The keys in an AVObject can only contain letters, numbers, and underscores. A custom key cannot start with
__(double underscores). The values in an AVObject can be strings, numbers, booleans, arrays, or dictionaries. LeanCloud stores data in the format of JSON, so any objects that can be converted into JSON can be stored on LeanCloud. Besides the basic types, LeanCloud can also handle dates,Bytes, and files. To summarize, the types allowed in an AVObject include:StringNumberBooleanArrayObjectDateBytes(base64-encoded binary data)FileNull(see notes below)You cannot set a field to
nullvia SDKs. It is not recommended to set a field tonullvia REST API. You can leave the field unset instead.An
Objectcan contain key-value pairs with each value to be a JSON-compatible object. Keep in mind that the key of anObjectcannot be__typeor contain$or.since they are reserved for special purposes.ACL,className,createdAt,objectId, andupdatedAtare also reserved fields and cannot be used as custom keys.Our SDKs can handle certain conversions between native types (for Objective-C and Java) and JSON. For example, when you are saving an
NSString, it will be automatically converted to aString.There are two ways to store binary data. When storing small pieces of data, you can use
Byteswhich allows you to writeNSDataorbytes[]directly into an AVObject. When storing actual files (like images, videos, and documents), you can store them as AVFiles withFileand link them to existing AVObjects.Data Type Solidification
When a class is first created, it does not contain a predefined schema. Therefore, for the first object being saved with it, the fields of it can hold any types of values that are supported.
However, when a field is saved for at least one time, the type of data it can accept will be restricted to those saved in the past. For example, if a
Userobject is saved with itsnameto be aString, then all theUserobjects saved after that must have theirnameto beString(SDK will return an error if you attempt to save other types of data).One exception is that all the fields can accept
nullregardless of their types. Keep in mind that if a field is saved for the first time withnullas its value, the type of this field will be locked toObject. This may lead to unexpected outcomes in some instances. For example, if aUserobject has a fieldnicknameand the first user being created doesn't set a nickname, then if the user is saved withnicknameto benull, the type ofnicknamewill be locked toObject. If this user or another user ever set a string for this field, an error will be thrown. Therefore, it is discouraged that you setnullas the value of a field. If a field doesn't have a value, you may simply skip setting a value for the field. In Java SDK, the operation of settingnullas a value will be ignored, which means thatput(key, null)will not trigger any effect.Once the type of a field is solidified, it cannot be changed unless you delete and recreate that field. For example, if there is a
StringfieldindexIdholding numbers as strings and you need to change its type toNumber, you may create a temporary field, copy the original data into there, delete the existingindexId, and copy the data back from the temporary field.Data Management
You can manage the data in your application by going to Dashboard > LeanStorage > Data in your browser. This web console shows all the objects stored in your application in JSON.
Keep in mind that:
nullas a value will set the value to be the empty valuenullrather than the string"null".objectId,createdAt, andupdatedAtare set by the system automatically and cannot be edited.Data Relationships
As mentioned earlier, LeanCloud doesn't use primary keys or foreign keys to build relationships between AVObjects. The following entities are used instead:
You can store the pointer to an object as a property of another project. This is often used for one-to-one and one-to-many relationships.
You can store an array of pointers as a property of another project. This is often used for one-to-many and many-to-many relationships.
You can create a class that links objects from other classes and attach additional information for each relationship. For example, when building a social network, you can have two fields of this class for followers and followees and have a third field for the times the relationships are formed.
See Data Modeling for more instructions.
AVQuery
Since LeanCloud adopts a data model that's different from those of relational databases, AVQuery is used in place of SQL for querying data. With AVQuery, you can:
AVFile
Besides basic types of data, files like images, videos, and documents, as well as binary data, can also be stored on LeanCloud. Since data larger than 128 KB cannot be written into an AVObject, AVFile becomes a better carrier for it. AVFile also works with CDN so that files in your app can be delivered faster to the users. You can access AVFiles with either a shared domain or your own domains (recommended). Both HTTP and HTTPS are supported.
AVUser
Almost all apps need a user system to store information related to users. With AVUser, you can quickly implement functions like signing up with email or phone number and logging in with phone verification code.
A user can sign up or log in with the following methods:
A user can also reset their password with email or phone number. See the guides of each SDK for more details.
Hooks
See Cloud Function Guide > Hooking.
Key Metrics
LeanCloud guarantees a 99.9% service availability and ensures a high capability and scalability for your business:
Native SDKs
Here is a list of guides for the SDK of each platform:
Objective-C Guide
See LeanStorage Objective-C Guide.
JavaScript Guide
See LeanStorage JavaScript Guide.
Python Guide
See LeanStorage Python Guide.
PHP Guide
See LeanStorage PHP Guide.
Java Guide
See LeanStorage Java Guide.
Swift Guide
See LeanStorage Swift Guide.
REST API
See LeanStorage REST API.