# !store.get

The `!store.get` YAML function allows retrieving arbitrary keys directly from a [store](/cli/configuration/stores)
without following the Atmos stack/component/key naming convention. This is useful for accessing values stored by external systems
or for retrieving global configuration that doesn't belong to a specific component.

### Usage

The `!store.get` function is called with two parameters, and optionally a default value and
a [YQ](https://mikefarah.gitbook.io/yq) query expression:

```yaml
  !store.get <store_name> <key> | default <default-value> | query <yq-expression>
```

Usage examples:

**File:** `stack.yaml`

```yaml
# Get an arbitrary key from the store
  !store.get <store_name> <key>

  # Get a key and provide a default value
  !store.get <store_name> <key> | default <default-value>

  # Get a key and extract a value using a YQ expression
  !store.get <store_name> <key> | query <yq-expression>

  # Combine default value and query expression
  !store.get <store_name> <key> | default "{}" | query .field
```

### Arguments

- **`store_name`**
  The name of the store to read from (as defined in the 
  `atmos.yaml`
   file)
- **`key`**
  The exact key name or path to retrieve from the store. This is the literal key as it exists in the store, not constructed from stack/component/key patterns
- **`default-value`**
  (optional) The default value to return if the key is not found in the store
- **`yq-expression`**
  (optional) 
  [YQ](https://mikefarah.gitbook.io/yq)
   expression to retrieve individual values from the result

:::tip
You can use [Atmos Stack Manifest Templating](/templates) in the `!store.get` YAML function expressions.
Atmos processes the templates first, and then executes the `!store.get` function, allowing you to provide the key name
dynamically.
:::

### Key Differences from [`!store`](/functions/yaml/store)

| Feature           | `!store`                                        | `!store.get`                                    |
|-------------------|-------------------------------------------------|-------------------------------------------------|
| **Key Format**    | Constructs key from stack/component/key pattern | Uses exact key as provided                      |
| **Use Case**      | Retrieve Atmos-managed component outputs        | Retrieve arbitrary values from external systems |
| **Key Pattern**   | `prefix/stack/component/key`                    | Any format the store supports                   |
| **Typical Usage** | Cross-component dependencies                    | Global configs, externally managed values       |

:::tip
If you need to retrieve values that follow the Atmos stack/component/key pattern, use the
[`!store`](/functions/yaml/store) function instead, as it provides better integration with Atmos component dependencies.
:::

:::note Type-Aware Merging
Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
:::

### Using YQ Expressions

You can use [YQ](https://mikefarah.gitbook.io/yq) expressions to extract specific values
from complex data structures:

**File:** `stack.yaml`

```yaml
# Extract database host from app-config in Redis
database_host: !store.get redis app-config | query .database.host

# Get the first availability zone from Azure Key Vault array
primary_zone: !store.get azure-keyvault availability-zones | query .[0]

# Extract API key from SSM config with empty object fallback
api_key: !store.get ssm /external/config | default "{}" | query .api.key
```

### Examples

#### Redis Store

**File:** `stack.yaml`

```yaml
vars:
  # Retrieve a global configuration object
  global_config: !store.get redis global-config

  # Get a specific field from the configuration
  api_version: !store.get redis global-config | query .version

  # Use templating to construct the key dynamically
  regional_config: !store.get redis "config-{{ .vars.region }}"
```

#### AWS SSM Parameter Store

**File:** `stack.yaml`

```yaml
vars:
  # Retrieve a parameter by its full path
  database_password: !store.get ssm /myapp/prod/db/password

  # Get a parameter with a default value
  feature_flag: !store.get ssm /features/new-feature | default "disabled"
```

#### Azure Key Vault

**File:** `stack.yaml`

```yaml
vars:
  # Retrieve a secret by its exact name
  api_secret: !store.get azure-keyvault external-api-key

  # Get a certificate with error handling
  ssl_cert: !store.get azure-keyvault ssl-certificate | default ""
```

#### Google Secret Manager

**File:** `stack.yaml`

```yaml
vars:
  # Retrieve a secret by its resource ID
  service_account: !store.get gsm projects/my-project/secrets/service-account/versions/latest

  # Parse JSON secret and extract a field
  client_id: !store.get gsm oauth-config | query .client_id
```

### Considerations

- **Exact Key Matching**: The key you provide must match exactly how it is stored in the backend, including any required
  prefix, path, or normalization specific to that store
- **External Systems**: This function is ideal for interoperability with values written by external systems that don't
  follow Atmos naming conventions
- **Performance**: Direct key access is typically faster than pattern-based retrieval since no key construction is needed
- **Security**: Like `!store`, `!store.get` reads values in cleartext and cannot read stores marked `secret: true`. For secrets, mark the store [`secret: true`](/cli/configuration/secrets) and read it with [`!secret`](/functions/yaml/secret), which masks values and gates access
- **Access Control**: Ensure your store credentials have permission to access the keys you're trying to retrieve