Using Collections
This section assumes you have already read the overview and understand what collections are and what they are for.
Creating collections
When creating collections, you need to pass the collection type as the first parameter, followed by the metadata and the content.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Fetching collections
Fetching the list of collections is easy, and is the first step in any Etebase application, because collections contain the data.
Simple fetch
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
The number of returned collections is limited by default, and you can control this limit by passing a different limit parameter as we'll see in the next example:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
You can also fetch multiple collection types at the same time:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Only fetch recent changes
We can use the stoken
we have gotten in previous fetches to only return changed collections. A collection is considered changed if either it or any of its items have changed.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Fetch in chunks
We can use a combination of limit and stoken to fetch the changes in chunks rather than all at once. This is more resistant to spotty internet connections, and means we can show data to users faster.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
uid
Fetch by Sometimes we don't care about getting the whole list of collections, and we are just interested in fetching one collection based on its uid
. We can do it like this:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Removed memberships
When a collection is deleted it will be marked as deleted and signed so clients can verify it was really deleted by the owner rather than forged by the server.
However, when a user loses access to a collection it's not marked as deleted. Instead, its uid
is returned in a special list. Here is how it looks:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Note: because membership removals are not signed, it's good practice to show an indication to the user before removing the local copy.
Modifying and deleting collections
Modifying collections is easy, it's just a matter of changing them and uploading them.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Deleting is even easier:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Advanced uploads and transactions
In the examples above we always uploaded the collections in a way that overwrote whatever is on the server, regardless if it has changed since we last fetched it, or not. While this is fine in many cases, in some cases you want to prevent that in order to ensure the consistency of data.
Transactions
The easiest way to ensure consistency is just to use transactions. Transactions make sure that what we think is the most recent version, really is, and will fail otherwise.
For example:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
stoken
Using Transactions will only fail if the collection itself has changed, but will not fail if one of its items has changed. In some cases we want to have collection-wide consistency and want to make sure nothing has changed.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Binary content
In the examples above content was always a string. However, content is actually a binary blob of data, not a string. Using it as a string is just a convenience.
Here is how you can control the formatting of the data:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust