feat(docs): Multiple datasets

sources/platform/actors/development/actor_definition/actor_json.md

@@ -81,6 +81,7 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on
 | `input` | Optional | You can embed your [input schema](./input_schema/index.md) object directly in `actor.json` under the `input` field. You can also provide a path to a custom input schema. If not provided, the input schema at `.actor/INPUT_SCHEMA.json` or `INPUT_SCHEMA.json` is used, in this order of preference. |
 | `changelog` | Optional | The path to the CHANGELOG file displayed in the Information tab of the Actor in Apify Console next to Readme. If not provided, the CHANGELOG at `.actor/CHANGELOG.md` or `CHANGELOG.md` is used, in this order of preference. Your Actor doesn't need to have a CHANGELOG but it is a good practice to keep it updated for published Actors. |
 | `storages.dataset` | Optional | You can define the schema of the items in your dataset under the `storages.dataset` field. This can be either an embedded object or a path to a JSON schema file. [Read more](/platform/actors/development/actor-definition/dataset-schema) about Actor dataset schemas. |
+| `storages.datasets` | Optional | You can define multiple datasets for the Actor under the `storages.datasets` field. This can be an object containing embedded objects or paths to a JSON schema files. [Read more](/platform/actors/development/actor-definition/dataset-schema/multiple-datasets) about multiple dataset schemas. |
 | `defaultMemoryMbytes` | Optional | Specifies the default amount of memory in megabytes to be used when the Actor is started. Can be an integer or a [dynamic memory expression string](./dynamic_actor_memory/index.md). |
 | `minMemoryMbytes` | Optional | Specifies the minimum amount of memory in megabytes required by the Actor to run. Requires an _integer_ value. If both `minMemoryMbytes` and `maxMemoryMbytes` are set, then `minMemoryMbytes` must be equal or lower than `maxMemoryMbytes`. Refer to the [Usage and resources](https://docs.apify.com/platform/actors/running/usage-and-resources#memory) for more details about memory allocation. |
 | `maxMemoryMbytes` | Optional | Specifies the maximum amount of memory in megabytes required by the Actor to run. It can be used to control the costs of run, especially when developing pay per result Actors. Requires an _integer_ value. Refer to the [Usage and resources](https://docs.apify.com/platform/actors/running/usage-and-resources#memory) for more details about memory allocation. |

sources/platform/actors/development/actor_definition/dataset_schema/multiple_datasets.mdx

@@ -0,0 +1,143 @@
+---
+title: Multiple datasets
+description: Learn how to use multiple datasets within your Actors to organize and store different types of data separately.
+sidebar_position: 2
+slug: /actors/development/actor-definition/dataset-schema/multiple-datasets
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Actors that scrape different data types can store each type in its own dataset with separate validation rules. For example, an e-commerce scraper might store products in one dataset and categories in another.
+
+Each dataset:
+
+- Is created when the run starts
+- Follows the run's data retention policy
+- Can have its own validation schema
+
+## Define multiple datasets
+
+Define datasets in your Actor schema using the `datasets` object:
+
+```json title=".actor/actor.json"
+{
+    "actorSpecification": 1,
+    "name": "my-e-commerce-scraper",
+    "title": "E-Commerce Scraper",
+    "version": "1.0.0",
+    "storages": {
+        "datasets": {
+            "default": "./products_dataset_schema.json",
+            "categories": "./categories_dataset_schema.json"
+        }
+    }
+}
+```
+
+Provide schemas for individual datasets as file references or inline. Schemas follow the same structure as single-dataset schemas.
+
+The keys of the `datasets` object are aliases that refer to specific datasets. The previous example defines two datasets aliased as `default` and `categories`.
+
+:::info Alias versus named dataset
+
+Aliases and names are different. Named datasets have specific behavior on the Apify platform (the automatic data retention policy doesn't apply to them). Aliased datasets follow the data retention of their run. Aliases only have meaning within a specific run.
+
+:::
+
+Requirements:
+
+- The `datasets` object must contain the `default` alias
+- The `datasets` and `dataset` objects are mutually exclusive (use one or the other)
+
+See the full [Actor schema reference](../actor_json.md#reference).
+
+## Access datasets in Actor code
+
+Access aliased datasets: using the Apify SDK, or reading the `ACTOR_STORAGES_JSON` environment variable directly.
+
+### Apify SDK
+
+<Tabs groupId="main">
+<TabItem value="JavaScript" label="JavaScript">
+
+In the JavaScript/TypeScript SDK `>=3.7.0`, use `openDataset` with `alias` option:
+
+```js
+const categoriesDataset = await Actor.openDataset({alias: 'categories'});
+```
+
+:::note Running outside the Apify platform
+
+When the JavaScript SDK runs outside the Apify platform, aliases fall back to names (using an alias is the same as using a named dataset). The dataset is purged on the first access when accessed using the `alias` option.
+
+:::
+
+</TabItem>
+<TabItem value="Python" label="Python">
+
+In the Python SDK `>=3.3.0`, use `open_dataset` with `alias` parameter:
+
+```py
+categories_dataset = await Actor.open_dataset(alias='categories')
+```
+
+:::note Running outside the Apify platform
+
+When the Python SDK runs outside the Apify platform, it uses the [Crawlee for Python aliasing mechanism](https://crawlee.dev/python/docs/guides/storages#named-and-unnamed-storages). Aliases are created as unnamed and purged on Actor start.
+
+:::
+
+</TabItem>
+</Tabs>
+
+
+### Environment variable
+
+`ACTOR_STORAGES_JSON` contains JSON-encoded unique identifiers of all storages associated with the current Actor run. Use this approach when
+working without the SDK:
+
+```sh
+echo $ACTOR_STORAGES_JSON | jq '.datasets.categories'
+# This will output id of the categories dataset, e.g. `"3ZojQDdFTsyE7Moy4"`
+```
+
+
+## Configure the output schema
+
+### Storage tab
+
+The **Storage** tab in the Actor run view displays all datasets defined by the Actor and used by the run (up to 10).
+
+The Storage tab shows data but doesn't surface it clearly to end users. To present datasets more clearly, define an [output schema](../../actor_definition/output_schema/index.md).
+
+### Output schema
+
+Actors with output schemas can reference datasets through variables using aliases:
+
+```json
+{
+    "actorOutputSchemaVersion": 1,
+    "title": "Output schema",
+    "properties": {
+        "products": {
+            "type": "string",
+            "title": "Products",
+            "template": "{{storages.datasets.default.apiUrl}}/items"
+        },
+        "categories": {
+            "type": "string",
+            "title": "Categories",
+            "template": "{{storages.datasets.categories.apiUrl}}/items"
+        }
+    }
+}
+```
+
+[Read more](../output_schema/index.md#how-templates-work) about how templates work.
+
+## Billing for non-default datasets
+
+When an Actor uses multiple datasets, only items pushed to the `default` dataset trigger the built-in `apify-default-dataset-item` event. Items in other datasets are not charged automatically.
+
+To charge for items in other datasets, implement custom billing in your Actor code. Refer to the [billing documentation](../../../publishing/monetize/pay_per_event.mdx) for implementation details.

sources/platform/actors/development/programming_interface/environment_variables.md

@@ -44,6 +44,7 @@ Here's a table of key system environment variables:
 | `ACTOR_BUILD_TAGS` | A comma-separated list of tags of the Actor build used in the run. Note that this environment variable is assigned at the time of start of the Actor and doesn't change over time, even if the assigned build tags change. |
 | `ACTOR_TASK_ID` | ID of the Actor task. Empty if Actor is run outside of any task, e.g. directly using the API. |
 | `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for [events](/platform/actors/development/programming-interface/system-events) from Actor platform. |
+| `ACTOR_STORAGES_JSON` | JSON-encoded unique identifiers of storages associated with the current Actor run. |
 | `ACTOR_DEFAULT_DATASET_ID` | Unique identifier for the default dataset associated with the current Actor run. |
 | `ACTOR_DEFAULT_KEY_VALUE_STORE_ID` | Unique identifier for the default key-value store associated with the current Actor run. |
 | `ACTOR_DEFAULT_REQUEST_QUEUE_ID` | Unique identifier for the default request queue associated with the current Actor run. |