Using Items
This section assumes you have already read the overview and understand what collections and items are and what each are for.
Items are very similar to collections in how you interact with them, so this section may look familiar, especially if you just finished the previous one. However, there are some differences, especially when uploading data.
Prerequisite: have a collection
This section assumes you already have a collection created and uploaded. We already covered it in the previous section, but as a reminder:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Creating items
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Fetching items
Fetching items is very similar to fetching collections:
Simple fetch
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
The number of returned items 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
Only fetch recent changes
We can use the stoken
we have gotten in previous fetches to only return changed items.
- 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 items, and we are just interested in fetching one item based on its uid
. We can do it like this:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
uid
Fetch multiple by - JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Fetch a group of items
In addition to fetching all of the changes in a collection, you can also limit the fetching to only a specific subset of items. This is useful, for example, if your data is structured hierarchically (e.g. a directory tree), and you are only interested in refreshing the currently viewed directory.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Modifying and deleting items
Modifying items 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
Uploading multiple items
As you saw in the previous examples, unlike the collection's upload
, batch
accepts an array of items. This can be used for uploading multiple items at once:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Advanced uploads and transactions
In the examples above we always uploaded the items 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. This consistency check is done across all of the items, and if one item fails the check, the whole transaction fails.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
stoken
Using Like with collections, transactions will only fail if the items themselves have changed, but will not fail if another item of the collection 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
Additional dependencies
Sometimes we may want a transaction
or batch
upload to fail if some items have changed but not upload them. These are called dependencies and can be passed to both transactions and batches.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Treating collections as items
In the examples above we only covered consistency of items, but what happens if we want to ensure the collection itself is consistent with its items? One case where this is useful, is if your data is ordered hierarchically (e.g. as a tree) with the collection as the root. In this case, you will want to be able to create a child and have it added to the root node in the same transaction.
In Etebase, collections are essentially just items with some extra data, so you can use collections directly as items with just a small difference.
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
You can also fetch the collection as an item from all of the item API functions:
- JavaScript
- Python
- Java
- Kotlin
- C/C++
- Rust
Subscriptions (live updates)
Some applications are interactive in nature and their data changes often. For these applications it's useful to be able to subscribe to live-updates so your app gets notified the moment data is changed. This is what live updates are for.
- 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