> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/platform-administration/settings/multi-instance.md).
# Multi-Instance
Learn more about multi-instance functionality that allows the deployment of the same pipeline multiple times with different parameters.
## **Overview**
### **What is a multi-instance pipeline**
A multi-instance pipeline is a pipeline that you build once and deploy several times, with different parameters in each deployment. Each deployment is an instance. All instances share the same integration flow, but each one runs with its own values, such as a different account, store, or date range.
### **Why use multi-instance pipelines**
Without multi-instance pipelines, running the same logic against different targets means maintaining one copy of the pipeline for each target. With multi-instance, you keep a single pipeline, and any change to the flow applies to all instances.
### **How it works**
A multi-instance setup has four parts:
* **Multi-instance model:** Defines the fields (variables) that each instance must fill in.
* **Instance:** Sets its own values for the model fields in each environment.
* **Multi-instance pipeline:** References the model fields in triggers and account fields, using the `{{replica.field-name}}` pattern.
* **Deployment:** Runs the pipeline with the values of one instance, so you deploy the pipeline once per instance.
### **Use cases**
#### **Accelerated data extraction**
You can use multi-instance pipelines to extract large amounts of data from a database quickly and safely. Split the extraction into instances that each cover a specific date range, all using the same extraction logic:
| Instance | Interval |
| -------- | ---------------- |
| Period 1 | October 1 to 8 |
| Period 2 | October 8 to 16 |
| Period 3 | October 16 to 24 |
| Period 4 | October 24 to 31 |
The Period 1 instance extracts all data between October 1 and October 8, over as many executions as needed. The other instances use the same logic for their own intervals. You could run this extraction with a single pipeline, but with multiple instances the extraction can be up to four times faster.
#### **Same query in different environments**
You can also use a multi-instance pipeline to run an identical query against databases installed in different environments.
## **Step-by-step guide**
### **Step 1: Create the multi-instance model**
1. Go to **Settings**, open the **Multi-Instance** page, and click **Create**.
2. Fill in the model information:
* **Name:** Name of the multi-instance model.
* **Description:** Description of the multi-instance model.
* **Field:** The variables that receive a value in each instance. You use these names later in the pipeline.
3. Click **Confirm**.
After creating a model, you can:
* **Edit:** Change the name, description, and fields.
* **Configure:** Create instances and set their values.
* **Delete:** Remove a model that is no longer used by any pipeline, whether deployed, undeployed, or archived.
### **Step 2: Configure the instances**
1. Find the model you created and click **Configure**.
2. Create the instances one by one and set a value for each field in each environment tab (for example, test and prod).
3. Click **Save**.
In the following example, "instance1" and "instance2" represent two stores. Each one has its own values for test and prod.
### **Step 3: Set the pipeline as multi-instance**
You can convert any pipeline to multi-instance, whether it's deployed or not.
{% hint style="danger" %}
After you set a pipeline as multi-instance, you can't turn this setting off.
{% endhint %}
1. In the pipeline, click **Settings** and turn on **Is it a multi-instance?**.
2. Select the multi-instance model the pipeline uses.
### **Step 4: Use instance variables in the pipeline**
To make the pipeline use different values in each instance, add instance variables to it. An instance variable follows the `{{replica.field-name}}` pattern, where `field-name` is the name of a field you created in Step 1. For example, a field named `account-name` becomes `{{replica.account-name}}`.
When you deploy the pipeline, the platform replaces each variable with the value set for that instance.
#### **Use instance variables in the trigger**
You can use instance variables in the trigger configuration with the `{{replica.field-name}}` pattern. For example, if the pipeline uses an [Event Trigger](/documentation/connectors-and-triggers/triggers/messaging-and-events/event.md), add an instance variable to the event name:
#### **Use a different account for each instance**
Each instance can use its own account. To set this up, replace the selected account with an instance variable in the connector configuration. This works in connectors and capsules, including connectors with more than one account field, such as **Custom Account #1** and **Custom Account #2**.
1. Open the component configuration and find the **Account** field.
2. Click the curly braces (`{ }`) button next to the field label. The field switches from the account list to an editor.
3. Enter the instance variable, for example `{{replica.account-name}}`. Autocomplete suggests the `replica` and `global` scopes, but not the model field names, so type the field name exactly as it appears in the model.
To go back to the account list, click the curly braces button again. Switching back clears the field, so the expression you typed is lost.
The curly braces button appears in all multi-instance pipelines. In other pipelines, it appears only when the account field already contains an instance variable, so you can switch back to the account list.
You set the value of the variable for each instance on the **Multi-Instance** page in **Settings**. Open the instance and go to the corresponding environment tab, as shown in Step 2.
#### **Test the pipeline with an instance**
In the Execution Panel, select the instance in the **Payload** tab. The execution uses the values configured for that instance in the `{{replica.field-name}}` variables.
### **Step 5: Deploy the pipeline on each instance**
1. Go to **Run**, select the environment in the upper-left corner, and click **Create**.
2. Select the pipeline and its version.
3. Select the instance you want to deploy the pipeline on.
4. Configure the other deployment settings, such as size, concurrent executions, and replicas. To learn more about these settings, read [How to deploy or redeploy a pipeline](/documentation/development-cycle/overview/deployment/deployments.md).
5. Click **Deploy**.
Repeat these steps for each instance.
After deployment, the instance name is added to the pipeline name. For example, "multi-instance-pipeline" deployed on "instance1" appears as "multi-instance-pipeline-instance1".
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.digibee.com/documentation/platform-administration/settings/multi-instance.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
