From 31482e82b1e098c3a0b10fd9dd2fd1e1a8d2f1d8 Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Mon, 7 Jul 2025 17:58:08 +0200 Subject: [PATCH] docs: datastore vs storage Signed-off-by: David Dal Busco --- docs/build/authentication/index.md | 2 +- docs/build/components/datastore-storage.md | 27 ++++++++++++++++++++ docs/build/datastore/{index.md => index.mdx} | 12 +++++++-- docs/build/storage/development.mdx | 2 +- docs/build/storage/{index.md => index.mdx} | 10 +++++++- docs/faq.md | 2 +- docs/guides/angular.mdx | 4 +-- docs/guides/nextjs.mdx | 4 +-- docs/guides/react.mdx | 4 +-- docs/guides/sveltekit.mdx | 4 +-- docs/guides/vue.mdx | 4 +-- docs/intro.mdx | 4 +-- docs/miscellaneous/access-keys.md | 2 +- docs/miscellaneous/memory.md | 4 +-- docs/terminology.md | 2 +- 15 files changed, 65 insertions(+), 22 deletions(-) create mode 100644 docs/build/components/datastore-storage.md rename docs/build/datastore/{index.md => index.mdx} (90%) rename docs/build/storage/{index.md => index.mdx} (91%) diff --git a/docs/build/authentication/index.md b/docs/build/authentication/index.md index 4e03de6e..89e126c8 100644 --- a/docs/build/authentication/index.md +++ b/docs/build/authentication/index.md @@ -16,7 +16,7 @@ Juno allows you to securely identify users **anonymously** and save their data o Our easy-to-use SDKs support authentication through [Internet Identity] and [NFID]. -Juno Authentication integrates tightly with other Juno services like [datastore](../datastore/index.md) and [storage](../storage/index.md). +Juno Authentication integrates tightly with other Juno services like [datastore](../datastore/index.mdx) and [storage](../storage/index.mdx). You can manage your users in the [authentication](https://console.juno.build/authentication) view in Juno's console. A new entry is created when a user successfully signs in. diff --git a/docs/build/components/datastore-storage.md b/docs/build/components/datastore-storage.md new file mode 100644 index 00000000..7661bdb0 --- /dev/null +++ b/docs/build/components/datastore-storage.md @@ -0,0 +1,27 @@ +Juno gives you two ways to persist data. Both follow a collections-based architecture, but they serve different purposes and behave differently in practice. + +| Feature | **Datastore** (Structured) | **Storage** (Files) | +| ---------------------- | -------------------------------- | --------------------------------------------- | +| Use case | App state, user profiles, config | Images, files, generated user content | +| Data format | JSON-like documents | Binary files | +| Identifier | `key` (string you define) | `fullPath` (auto or custom) | +| Accessible via web URL | No | Yes | +| Size limit | Max 2 MB per document | Chunked; limited by available Satellite space | + +**`key` vs `fullPath`** + +Both Datastore and Storage use a unique identifier per item — but they refer to different things and are used differently. + +- **Datastore → `key`**: + + - A unique string you assign to each document within a collection. + - Used to retrieve, update, or delete a specific document. + - Commonly a UUID (e.g. `crypto.randomUUID()`), a nanoid, or any meaningful string like a slug or user ID. + - Example: `bafkb4by...`, `user:42`, or `config/theme`. + +- **Storage → `fullPath`**: + - The full path of an asset used to build a valid web URL. + - It's automatically generated from the uploaded filename unless explicitly set. + - The `fullPath` must include the collection name (except for your app's frontend assets like HTML, JS, etc.). + - Used to serve, list, or delete files. + - Example: `/images/logo.png` (collection: `images`) or `/avatars/user42/profile.jpg` (collection: `avatars`). diff --git a/docs/build/datastore/index.md b/docs/build/datastore/index.mdx similarity index 90% rename from docs/build/datastore/index.md rename to docs/build/datastore/index.mdx index ae0bf532..2026ff76 100644 --- a/docs/build/datastore/index.md +++ b/docs/build/datastore/index.mdx @@ -12,7 +12,7 @@ Use it for structured data like user profiles, tasks, settings, or other data of :::tip -For binary files like images or files, use the [Storage](../storage/index.md) instead. +For binary files like images or files, use the [Storage](../storage/index.mdx) instead. ::: @@ -40,7 +40,7 @@ In essence, a "Datastore" functions as a keypair store. Each satellite has specific memory limits. For detailed information, please refer to the related [documentation](../../miscellaneous/memory.md) page. -As for documents, they can be up to 2MB in size. However, larger files can be saved in the [storage](build/storage/index.md). +As for documents, they can be up to 2MB in size. However, larger files can be saved in the [storage](build/storage/index.mdx). --- @@ -49,3 +49,11 @@ As for documents, they can be up to 2MB in size. However, larger files can be sa The Datastore supports various configuration options to fine-tune its behavior, such as resource limits and operational constraints. For a detailed explanation of all available options, see the [configuration](../../reference/configuration.mdx#datastore) section. [satellite]: ../../terminology.md#satellite + +--- + +## Datastore vs Storage + +import DatastoreVsStorage from "../components/datastore-storage.md"; + + diff --git a/docs/build/storage/development.mdx b/docs/build/storage/development.mdx index c4b7442d..adc1cae0 100644 --- a/docs/build/storage/development.mdx +++ b/docs/build/storage/development.mdx @@ -372,7 +372,7 @@ There are multiple ways to delete assets from your Storage. ### Delete asset -To delete an asset, you only need to provide its `fullPath`. Unlike the [datastore](../datastore/index.md), there is no timestamp validation performed when deleting an asset. +To delete an asset, you only need to provide its `fullPath`. Unlike the [datastore](../datastore/index.mdx), there is no timestamp validation performed when deleting an asset. ```typescript import { deleteAsset } from "@junobuild/core"; diff --git a/docs/build/storage/index.md b/docs/build/storage/index.mdx similarity index 91% rename from docs/build/storage/index.md rename to docs/build/storage/index.mdx index 59236d01..9c2047f7 100644 --- a/docs/build/storage/index.md +++ b/docs/build/storage/index.mdx @@ -11,7 +11,7 @@ It provides a simple way to upload, serve, and delete files, with support for mu :::tip -For structured data, use the [Datastore](../datastore/index.md) instead. +For structured data, use the [Datastore](../datastore/index.mdx) instead. ::: @@ -53,4 +53,12 @@ If you're configuring the hosting behavior of your site, start by checking out t For a complete list of available Storage options, refer to the [configuration](../../reference/configuration.mdx) section. +--- + +## Datastore vs Storage + +import DatastoreVsStorage from "../components/datastore-storage.md"; + + + [satellite]: ../../terminology.md#satellite diff --git a/docs/faq.md b/docs/faq.md index 58a6ded8..bec0d42e 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -32,7 +32,7 @@ In the unlikely event of Juno's disappearance, you, as the sole controller of yo ### Can I just deploy my website on the Internet Computer? -Absolutely! With Juno, you have the flexibility to choose the level of functionality you want for your project. Whether you simply want to host your static website on the [Internet Computer] or take advantage of Juno's rich features like [authentication](build/authentication/index.md), [datastore](./build/datastore/index.md), and [storage](./build/storage/index.md) for building dynamic dapps, the choice is yours. +Absolutely! With Juno, you have the flexibility to choose the level of functionality you want for your project. Whether you simply want to host your static website on the [Internet Computer] or take advantage of Juno's rich features like [authentication](build/authentication/index.md), [datastore](build/datastore/index.mdx), and [storage](build/storage/index.mdx) for building dynamic dapps, the choice is yours. ### Is Juno a project of the DFINITY foundation? diff --git a/docs/guides/angular.mdx b/docs/guides/angular.mdx index da092958..416b6418 100644 --- a/docs/guides/angular.mdx +++ b/docs/guides/angular.mdx @@ -153,8 +153,8 @@ import WhatsNext from "./components/whats-next.md"; This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features: - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication. -- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information. -- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos. +- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information. +- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos. Using the Juno CLI, you can easily scaffold this app. diff --git a/docs/guides/nextjs.mdx b/docs/guides/nextjs.mdx index c0b3739e..330cc8dc 100644 --- a/docs/guides/nextjs.mdx +++ b/docs/guides/nextjs.mdx @@ -157,8 +157,8 @@ import WhatsNext from "./components/whats-next.md"; This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features: - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication. -- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information. -- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos. +- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information. +- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos. Using the Juno CLI, you can easily scaffold this app. diff --git a/docs/guides/react.mdx b/docs/guides/react.mdx index 1db28c6e..a8fd3f9c 100644 --- a/docs/guides/react.mdx +++ b/docs/guides/react.mdx @@ -150,8 +150,8 @@ import WhatsNext from "./components/whats-next.md"; This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features: - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication. -- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information. -- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos. +- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information. +- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos. Using the Juno CLI, you can easily scaffold this app. diff --git a/docs/guides/sveltekit.mdx b/docs/guides/sveltekit.mdx index 8bffe62e..12bdb6b4 100644 --- a/docs/guides/sveltekit.mdx +++ b/docs/guides/sveltekit.mdx @@ -150,8 +150,8 @@ import WhatsNext from "./components/whats-next.md"; This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features: - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication. -- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information. -- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos. +- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information. +- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos. Using the Juno CLI, you can easily scaffold this app. diff --git a/docs/guides/vue.mdx b/docs/guides/vue.mdx index fb729756..2f542340 100644 --- a/docs/guides/vue.mdx +++ b/docs/guides/vue.mdx @@ -142,8 +142,8 @@ import WhatsNext from "./components/whats-next.md"; This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features: - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication. -- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information. -- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos. +- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information. +- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos. Using the Juno CLI, you can easily scaffold this app. diff --git a/docs/intro.mdx b/docs/intro.mdx index c870096e..755e3638 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -47,8 +47,8 @@ And during development, the environment mirrors production as closely as possibl Learn more about the available products, from auth and data to hosting and functions. - [Authentication](build/authentication/index.md) -- [Datastore](build/datastore/index.md) -- [Storage](build/storage/index.md) +- [Datastore](build/datastore/index.mdx) +- [Storage](build/storage/index.mdx) - [Hosting](build/hosting/index.md) - [Functions](build/functions/index.md) - [Analytics](build/analytics/index.md) diff --git a/docs/miscellaneous/access-keys.md b/docs/miscellaneous/access-keys.md index 08cfb665..e481a53b 100644 --- a/docs/miscellaneous/access-keys.md +++ b/docs/miscellaneous/access-keys.md @@ -31,7 +31,7 @@ Each access key is assigned a **role** that defines what it can do: | **Write** | Editor | ✅ | ✅ | ✅ | ❌ | | **Submit** | Submitter | ✅ | ❌ | ❌ | ❌ | -An **administrator** can perform tasks such as configuring or deploying an app, topping up a mission control or satellite, creating a new collection in the [datastore](../build/datastore/index.md) or [storage](../build/storage/index.md), or configuring a custom domain in the [hosting](../build/hosting/index.md). +An **administrator** can perform tasks such as configuring or deploying an app, topping up a mission control or satellite, creating a new collection in the [datastore](../build/datastore/index.mdx) or [storage](../build/storage/index.mdx), or configuring a custom domain in the [hosting](../build/hosting/index.md). An **editor** can publish new serverless function versions to a Satellite’s CDN, deploy your frontend application, and read data from a collection. However, it cannot directly upgrade a Satellite or start/stop a module. diff --git a/docs/miscellaneous/memory.md b/docs/miscellaneous/memory.md index 7b120fc9..4e493957 100644 --- a/docs/miscellaneous/memory.md +++ b/docs/miscellaneous/memory.md @@ -6,7 +6,7 @@ This page explains how memory works conceptually and how you can monitor its usa ## General Memory Usage -Every module — whether it's a [satellite], [orbiter], or your [mission control] — consumes memory in multiple ways. Some of that memory is directly controlled by your code, like the data you store in your [datastore](../build/datastore/index.md) or [storage](../build/storage/index.md). Other parts are more structural: global variables, the WASM binary (the container code itself), snapshots, and even system metadata contribute to your overall memory footprint. +Every module — whether it's a [satellite], [orbiter], or your [mission control] — consumes memory in multiple ways. Some of that memory is directly controlled by your code, like the data you store in your [datastore](../build/datastore/index.mdx) or [storage](../build/storage/index.mdx). Other parts are more structural: global variables, the WASM binary (the container code itself), snapshots, and even system metadata contribute to your overall memory footprint. To help you understand and optimize memory usage, the Console displays a detailed breakdown under each module's overview tab. These metrics are especially helpful for staying within limits, controlling costs, and avoiding issues during upgrades. @@ -53,7 +53,7 @@ In contrast, `heap` memory is best reserved for: - Serving your frontend assets (HTML, JS, images, etc.). - Small, ephemeral datasets that benefit from fast access and won't push the 1 GB heap limit. -This is why both the [datastore](../build/datastore/index.md) and [storage](../build/storage/index.md) support both memory types — but default to `stable`, which is also the **recommended** option. +This is why both the [datastore](../build/datastore/index.mdx) and [storage](../build/storage/index.mdx) support both memory types — but default to `stable`, which is also the **recommended** option. ### Default usage diff --git a/docs/terminology.md b/docs/terminology.md index 1d687c57..6d44431d 100644 --- a/docs/terminology.md +++ b/docs/terminology.md @@ -37,7 +37,7 @@ Learn more about [computation and storage costs](https://internetcomputer.org/do ## Doc -"doc" is a commonly used shorthand in Juno for a "document of the Datastore". Wherever you see the term "doc" in the codebase or documentation, it refers specifically to a document entity managed by the [Datastore](./build/datastore/index.md). This abbreviation is used for brevity and consistency throughout the project. +"doc" is a commonly used shorthand in Juno for a "document of the Datastore". Wherever you see the term "doc" in the codebase or documentation, it refers specifically to a document entity managed by the [Datastore](build/datastore/index.mdx). This abbreviation is used for brevity and consistency throughout the project. ## ICP