# Manage data storage in Amazon IoT SiteWise
Manage data storage

You can configure Amazon IoT SiteWise to save your data in the following storage tiers:

**Hot tier**  
 The hot storage tier is an Amazon IoT SiteWise managed time series storage. Hot tier is most effective for frequently accessed data, with low write-to-read latency. Data stored in the hot tier is used by industrial applications that need quick access to the latest values of measurements in your equipment. This includes applications that visualize real-time metrics with an interactive dashboard, or applications that monitor operations and launch alarms to identify performance issues.   
By default, data ingested into Amazon IoT SiteWise is stored in the hot tier. You can define a retention period for the hot tier, after which Amazon IoT SiteWise moves data in the hot tier to either warm or cold tier storage, based on your configuration. For best performance and cost efficiency, set your hot tier retention period to be longer than the time taken to retrieve data often. This is used for real time metrics, alarms, and monitoring scenarios. If a retention period is not set, your data is stored indefinitely in the hot tier. 

**Warm tier**  
 The warm storage tier is an Amazon IoT SiteWise managed tier that's effective for cost-efficient storage of historical data. It's best used to retrieve large volumes of data with medium write-to-read latency characteristics. Use the warm tier to store historical data that's needed for large workloads. For example, it's used for data retrieval for analytics, business intelligence applications (BI), reporting tools, and training of machine learning (ML) models. If you enable the cold storage tier, you can define a warm tier retention period. After the retention period ends, Amazon IoT SiteWise deletes data from the warm tier.

**Cold tier**  
The cold storage tier uses an Amazon S3 bucket to store data that's rarely used. With cold tier enabled, Amazon IoT SiteWise replicates the time series, including measurements, metrics, transforms and aggregates, and asset model definitions every 6 hours. Cold tier is used to store data that tolerates high read latency for historical reports and backups. 

**Topics**
+ [

# Configure storage settings in Amazon IoT SiteWise
](configure-storage.md)
+ [

# Troubleshoot storage settings for Amazon IoT SiteWise
](troubleshoot-storage-configuration.md)
+ [

# File paths and schemas of data saved in the cold tier
](file-path-and-schema.md)

# Configure storage settings in Amazon IoT SiteWise
Configure storage settings

You can configure storage settings to opt in to service managed warm tier storage, and also to replicate data to the cold tier. To learn more about the retention period for the warm and hot tier, see [Data retention impact](#retention-period). While configuring the storage settings, do the following:
+  **Hot tier retention** — Set a retention period for how long your data is stored in the hot tier before it's deleted, and moved to the service managed warm tier storage or cold tier storage based on your storage settings. Amazon IoT SiteWise will delete any data in the hot tier that existed before the retention period ends. If you don't set a retention period, your data is stored indefinitely in the hot tier. 
+  **Warm tier retention** — Set a retention period for how long your data is stored in the warm tier before it’s deleted from Amazon IoT SiteWise storage and moved to the customer managed cold tier storage. Amazon IoT SiteWise deletes any data from the warm tier that existed before the retention period ends. If a retention period is not set, your data is stored indefinitely in the warm tier.

**Note**  
To improve query performance, set a hot tier retention period with warm tier storage. 

## Impact of data retention in hot and warm tier storage
Data retention impact
+  When you decrease the retention period of the hot tier storage, data is permanently moved from the hot tier to the warm or cold tier. When you decrease the retention period of the warm tier, data is moved to the cold tier, and permanently deleted from the warm tier. 
+  When you increase the retention period of the hot or warm tier storage, the change affects data that's sent to Amazon IoT SiteWise from then on. Amazon IoT SiteWise does not retrieve data from the warm or cold storage to populate the hot tier. For example, if the retention period of the hot tier storage is initially set for 30 days and then increased to 60 days, it takes 30 days for the hot tier storage to contain 60 days worth of data. 

**Topics**
+ [

## Impact of data retention in hot and warm tier storage
](#retention-period)
+ [

## Configure storage settings for warm tier (console)
](#configure-storage-console-warm)
+ [

## Configure storage settings for warm tier (Amazon CLI)
](#configure-storage-cli-warm)
+ [

## Configure storage settings for cold tier (console)
](#configure-storage-console)
+ [

## Configure storage settings for cold tier (Amazon CLI)
](#configure-storage-cli)

## Configure storage settings for warm tier (console)
Configure for warm tier (console)

The following procedure shows you how to configure the storage settings to replicate data to the warm tier in the Amazon IoT SiteWise console.

**To configure storage settings in the console**

1. Navigate to the [Amazon IoT SiteWise console](https://console.amazonaws.cn/iotsitewise/).

1. In the navigation pane, under **Settings**, choose **Storage**.

1. In the upper-right corner, choose **Edit**.

1. On the **Edit storage** page, do the following:

1. For **Hot tier settings**, do the following:
   + If you want to set a retention period for how long your data is stored in the hot tier before it's deleted, and moved to the service managed warm tier storage, choose **Enable retention period**.
   +  To configure a retention period, enter a whole number and choose a unit. The retention period must be greater than or equal to 30 days. 

   Amazon IoT SiteWise deletes any data in the hot tier that's older than the retention period. If you don't set a retention period, your data is stored indefinitely.

1. (Recommended) For **Warm tier settings**, do the following:
   + To opt in to warm tier storage, select **I confirm to the opt-in of warm tier storage** to opt in for the warm tier storage.
   +  (Optional) To configure a retention period, enter a whole number and choose a unit. The retention period must be greater than or equal to 365 days. 

   Amazon IoT SiteWise deletes data in the warm tier that existed earlier than the retention period. If you don't set a retention period, your data is stored indefinitely.
**Note**  
When you opt in for warm tier, the configuration displays once only.
To set hot tier retention, you must have either warm or cold tier storage. For cost efficiency and historical data retrieval, Amazon IoT SiteWise recommends that you store long term data in the warm tier.
To set warm tier retention, you must have cold tier storage.

1. Choose **Save** to save your storage settings.

In the **Amazon IoT SiteWise storage** section, the **Warm tier storage** is in one of these states:
+ **Enabled** – If your data existed before the hot tier retention period, Amazon IoT SiteWise moves the data to the warm tier."
+ **Disabled** – The warm tier storage is disabled.

## Configure storage settings for warm tier (Amazon CLI)
Configure for warm tier (Amazon CLI)(

You can configure storage settings to move data to the warm tier by using the Amazon CLI and the following commands.

To prevent overriding the existing configuration, retrieve the current storage configuration information by running the following command:

```
aws iotsitewise describe-storage-configuration
```

**Example response without existing cold tier configuration**  

```
{
          "storageType": "SITEWISE_DEFAULT_STORAGE",
          "disassociatedDataStorage": "ENABLED",
          "configurationStatus": {
              "state": "ACTIVE"
          },
          "lastUpdateDate": "2021-10-14T15:53:35-07:00",
          "warmTier": "DISABLED"
}
```

**Example response with existing cold tier configuration**  

```
{             
      "storageType": "MULTI_LAYER_STORAGE",
          "multiLayerStorage": {
            "customerManagedS3Storage": {
            "s3ResourceArn": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/",
            "roleArn": "arn:aws:iam::aws-account-id:role/role-name"
            }
          },
      "disassociatedDataStorage": "ENABLED",
      "retentionPeriod": {
      "numberOfDays": retention-in-days
      },
       "configurationStatus": {
       "state": "ACTIVE"
      },
      "lastUpdateDate": "2023-10-25T15:59:46-07:00",
      "warmTier": "DISABLED"
}
```

### Configure storage settings for warm tier with Amazon CLI


Run the following command to configure the storage settings. Replace `file-name` with the name of the file that contains the Amazon IoT SiteWise storage configuration.

```
aws iotsitewise put-storage-configuration --cli-input-json file://file-name.json
```

**Example Amazon IoT SiteWise configuration with hot and warm tier**  

```
{
             "storageType": "SITEWISE_DEFAULT_STORAGE",
             "disassociatedDataStorage": "ENABLED",
             "warmTier": "ENABLED",
             "retentionPeriod": {
                "numberOfDays": hot-tier-retention-in-days
              } 
              
}
```
`hot-tier-retention-in-days` must be a whole number greater than or equal to 30 days.

**Example response**  

```
{
             "storageType": "SITEWISE_DEFAULT_STORAGE",
             "configurationStatus": {
             "state": "UPDATE_IN_PROGRESS"
             }
}
```

If you have cold tier storage enabled, see [Configure storage settings with Amazon CLI and existing cold tier](#configure-storage-cli-existing-cold).

### Configure storage settings with Amazon CLI and existing cold tier


**Configure storage settings using Amazon CLI with existing cold tier storage**
+ Run the following command to configure the storage settings. Replace *file-name* with the name of the file that contains the Amazon IoT SiteWise storage configuration.

  ```
  aws iotsitewise put-storage-configuration --cli-input-json file://file-name.json
  ```  
**Example Amazon IoT SiteWise storage configuration**  
  + Replace *amzn-s3-demo-bucket* with your Amazon S3 bucket name.
  + Replace *prefix* with your Amazon S3 prefix.
  + Replace *aws-account-id* with your Amazon account ID.
  + Replace *role-name* with the name of the Amazon S3 access role that allows Amazon IoT SiteWise to send data to Amazon S3.
  + Replace *hot-tier-retention-in-days* with a whole number greater than or equal to 30 days.
  + Replace *warm-tier-retention-in-days* with a whole number greater than or equal to 365 days.
**Note**  
Amazon IoT SiteWise will delete any data in the warm tier that's older than the retention period of the cold tier. If you don't set a retention period, your data is stored indefinitely.

  ```
  {
        "storageType": "MULTI_LAYER_STORAGE",
          "multiLayerStorage": {
            "customerManagedS3Storage": {
                "s3ResourceArn": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/",
                "roleArn": "arn:aws:iam::aws-account-id:role/role-name"
                }
            },
      "disassociatedDataStorage": "ENABLED",
      "retentionPeriod": {
        "numberOfDays": hot-tier-retention-in-days
      },
      "warmTier": "ENABLED",
      "warmTierRetentionPeriod": {
        "numberOfDays": warm-tier-retention-in-days
      }
  }
  ```  
**Example response**  

  ```
  {
        "storageType": "MULTI_LAYER_STORAGE",
        "configurationStatus": {
          "state": "UPDATE_IN_PROGRESS"
         }
  }
  ```

## Configure storage settings for cold tier (console)
Configure for cold tier (console)

The following procedure shows you how to configure the storage settings to replicate data to the cold tier in the Amazon IoT SiteWise console.

**To configure storage settings in the console**

1. Navigate to the [Amazon IoT SiteWise console](https://console.amazonaws.cn/iotsitewise/).

1. In the navigation pane, under **Settings**, choose **Storage**.

1. In the upper-right corner, choose **Edit**.

1. On the **Edit storage** page, do the following:

   1. For **Storage settings**, choose **Enable cold tier storage**. The cold tier storage is disabled by default.

   1. For **S3 bucket location**, enter the name of an existing Amazon S3 bucket and a prefix.
**Note**  
Amazon S3 uses the prefix as a folder name in the Amazon S3 bucket. The prefix must have 1-255 characters and end with a forward slash (/). Your Amazon IoT SiteWise data is saved in this folder.
If you don't have an Amazon S3 bucket, choose **View**, and then create one in the Amazon S3 console. For more information, see [Create your first S3 bucket](https://docs.amazonaws.cn/AmazonS3/latest/userguide/GetStartedWithS3.html#creating-bucket) in the *Amazon S3 User Guide*.

   1. For **S3 access role**, do one of the following:
      + Choose **Create a role from an Amazon managed template**, Amazon automatically creates an IAM role that allows Amazon IoT SiteWise to send data to Amazon S3.
      + Choose **Use an existing role**, and then choose the role that you created from the list.
**Note**  
You must use the same Amazon S3 bucket name for the **S3 bucket location** that you used in the previous step and in your IAM policy.
Make sure that your role has the permissions shown in the following example.  

**Example permissions policy:**    
****  

          ```
          {
                "Version":"2012-10-17",		 	 	 
                "Statement": [
                    {
                        "Effect": "Allow",
                        "Action": [
                            "s3:PutObject",
                            "s3:GetObject",
                            "s3:DeleteObject",
                            "s3:GetBucketLocation",
                            "s3:ListBucket"
                        ],
                        "Resource": [
                            "arn:aws-cn:s3:::amzn-s3-demo-bucket",
                            "arn:aws-cn:s3:::amzn-s3-demo-bucket/*"
                        ]
                    }
                ]
            }
          ```
Replace amzn-s3-demo-bucket with the name of your Amazon S3 bucket.
 If the Amazon S3 bucket is encrypted using a customer managed KMS key, the KMS key must have an access policy with an IAM role for `kms:Decrypt` and `kms:GenerateDataKey` operations. 

   1. To setup hot tier, see Step 5 in [Configure storage settings for warm tier (console)](#configure-storage-console-warm).

   1. (Optional) For **Amazon IoT Analytics integration**, do the following.
**Note**  
End of support notice: On December 15, 2025, Amazon will end support for Amazon IoT Analytics. After December 15, 2025, you will no longer be able to access the Amazon IoT Analytics console or Amazon IoT Analytics resources. For more information, see [Amazon IoT Analytics end of support](https://docs.amazonaws.cn/iotanalytics/latest/userguide/iotanalytics-end-of-support.html).

      1. If you want to use Amazon IoT Analytics to query your data, choose **Enabled Amazon IoT Analytics data store**.

      1. Amazon IoT SiteWise generates a name for your data store or you can enter a different name.

      Amazon IoT SiteWise automatically creates a data store in Amazon IoT Analytics to save your data. To query the data, you can use Amazon IoT Analytics to create datasets. For more information, see [Working with Amazon IoT SiteWise data](https://docs.amazonaws.cn/iotanalytics/latest/userguide/dataset-itsw.html) in the *Amazon IoT Analytics User Guide*.

   1. Choose **Save**.

In the **Amazon IoT SiteWise storage** section, the **Cold tier storage** can be one of the following values:
+ **Enabled** – Amazon IoT SiteWise replicates your data to the specified Amazon S3 bucket.
+ **Enabling** – Amazon IoT SiteWise is processing your request to enable the cold tier storage. This process can take several minutes to complete.
+ **Enable\$1Failed** – Amazon IoT SiteWise couldn't process your request to enable the cold tier storage. If you enabled Amazon IoT SiteWise to send logs to Amazon CloudWatch Logs, you can use these logs to troubleshoot issues. For more information, see [Monitor with Amazon CloudWatch Logs](monitor-cloudwatch-logs.md).
+ **Disabled** – The cold tier storage is disabled.

## Configure storage settings for cold tier (Amazon CLI)
Configure for cold tier (Amazon CLI)

The following procedure shows you how to configure the storage settings to replicate data to the cold tier using Amazon CLI.

**To configure storage settings using Amazon CLI**

1. To export data to an Amazon S3 bucket in your account, run the following command to configure the storage settings. Replace *file-name* with the name of the file that contains the Amazon IoT SiteWise storage configuration.

   ```
   aws iotsitewise put-storage-configuration --cli-input-json file://file-name.json
   ```  
**Example Amazon IoT SiteWise storage configuration**  
   + Replace *amzn-s3-demo-bucket* with your Amazon S3 bucket name.
   + Replace *prefix* with your Amazon S3 prefix.
   + Replace *aws-account-id* with your Amazon account ID.
   + Replace *role-name* with the name of the Amazon S3 access role that allows Amazon IoT SiteWise to send data to Amazon S3.
   + Replace *retention-in-days* with a whole number than is greater than or equal to 30 days.

   ```
   {
         "storageType": "MULTI_LAYER_STORAGE",
         "multiLayerStorage": {
             "customerManagedS3Storage": {
                 "s3ResourceArn": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/",
                 "roleArn": "arn:aws:iam::aws-account-id:role/role-name"
             }
         }, 
         "retentionPeriod": { 
             "numberOfDays": retention-in-days,
             "unlimited": false
         }
     }
   ```
**Note**  
You must use the same Amazon S3 bucket name in the Amazon IoT SiteWise storage configuration and IAM policy.
Make sure that your role has the permissions shown in the following example.  

**Example permissions policy:**    
****  

     ```
     {
           "Version":"2012-10-17",		 	 	 
           "Statement": [
               {
                   "Effect": "Allow",
                   "Action": [
                       "s3:PutObject",
                       "s3:GetObject",
                       "s3:DeleteObject",
                       "s3:GetBucketLocation",
                       "s3:ListBucket"
                   ],
                   "Resource": [
                       "arn:aws-cn:s3:::amzn-s3-demo-bucket",
                       "arn:aws-cn:s3:::amzn-s3-demo-bucket/*"
                   ]
               }
           ]
       }
     ```
Replace amzn-s3-demo-bucket with the name of your Amazon S3 bucket.
 If the Amazon S3 bucket is encrypted using a customer managed KMS key, the KMS key must have an access policy with an IAM role for `kms:Decrypt` and `kms:GenerateDataKey` operations.   
**Example response**  

   ```
   {
       "storageType": "MULTI_LAYER_STORAGE",
       "retentionPeriod": {
           "numberOfDays": 100,
           "unlimited": false
       },
       "configurationStatus": {
           "state": "UPDATE_IN_PROGRESS"
       }
   }
   ```
**Note**  
It can take a few minutes for Amazon IoT SiteWise to update the storage configuration.

1. To retrieve the storage configuration information, run the following command.

   ```
   aws iotsitewise describe-storage-configuration
   ```  
**Example response**  

   ```
   {
         "storageType": "MULTI_LAYER_STORAGE",
         "multiLayerStorage": {
             "customerManagedS3Storage": {
                 "s3ResourceArn": "arn:aws:s3:::amzn-s3-demo-bucket/torque/",
                 "roleArn": "arn:aws:iam::123456789012:role/SWAccessS3Role"
             }
         },
         "retentionPeriod": { 
             "numberOfDays": 100,
             "unlimited": false
         },
         "configurationStatus": {
             "state": "ACTIVE"
         },
         "lastUpdateDate": "2021-03-30T15:54:14-07:00"
     }
   ```

1. To stop exporting data to the Amazon S3 bucket, run the following command to configure storage settings.

   ```
   aws iotsitewise put-storage-configuration --storage-type SITEWISE_DEFAULT_STORAGE
   ```
**Note**  
By default, your data is only stored in the hot tier of Amazon IoT SiteWise.  
**Example response**  

   ```
   {
         "storageType": "SITEWISE_DEFAULT_STORAGE",
         "configurationStatus": {
             "state": "UPDATE_IN_PROGRESS"
         }
     }
   ```

1. To retrieve the storage configuration information, run the following command.

   ```
   aws iotsitewise describe-storage-configuration
   ```  
**Example response**  

   ```
   {
         "storageType": "SITEWISE_DEFAULT_STORAGE",
         "configurationStatus": {
             "state": "ACTIVE"
         },
         "lastUpdateDate": "2021-03-30T15:57:14-07:00"
     }
   ```

### (Optional) Create an Amazon IoT Analytics data store (Amazon CLI)


**Note**  
End of support notice: On December 15, 2025, Amazon will end support for Amazon IoT Analytics. After December 15, 2025, you will no longer be able to access the Amazon IoT Analytics console or Amazon IoT Analytics resources. For more information, see [Amazon IoT Analytics end of support](https://docs.amazonaws.cn/iotanalytics/latest/userguide/iotanalytics-end-of-support.html).

An Amazon IoT Analytics data store is a scalable and queryable repository that receives and stores data. You can use the Amazon IoT SiteWise console or Amazon IoT Analytics APIs to create an Amazon IoT Analytics data store to save your Amazon IoT SiteWise data. To query the data, you create datasets by using Amazon IoT Analytics. For more information, see [Working with Amazon IoT SiteWise data](https://docs.amazonaws.cn/iotanalytics/latest/userguide/dataset-itsw.html) in the *Amazon IoT Analytics User Guide*.

The following steps use Amazon CLI to create a data store in Amazon IoT Analytics.

To create a data store, run the following command. Replace *file-name* with the name of the file that contains the data store configuration.

```
aws iotanalytics create-datastore --cli-input-json file://file-name.json
```

**Note**  
You must specify the name of an existing Amazon S3 bucket. If you don't have an Amazon S3 bucket, create one first. For more information, see [Create your first S3 bucket](https://docs.amazonaws.cn/AmazonS3/latest/userguide/GetStartedWithS3.html#creating-bucket) in the *Amazon S3 User Guide*.
You must use the same Amazon S3 bucket name in the Amazon IoT SiteWise storage configuration, IAM policy, and Amazon IoT Analytics data store configuration.

**Example Amazon IoT Analytics data store configuration**  
Replace *data-store-name* and *amzn-s3-demo-bucket* with your Amazon IoT Analytics data store name and Amazon S3 bucket name.  

```
{
      "datastoreName": "data-store-name",
      "datastoreStorage": {
          "iotSiteWiseMultiLayerStorage": {
              "customerManagedS3Storage": {
                  "bucket": "amzn-s3-demo-bucket"
              }
          }
      },
      "retentionPeriod": {
          "numberOfDays": 90
      }
  }
```

**Example response**  

```
{
      "datastoreName": "datastore_IoTSiteWise_demo",
      "datastoreArn": "arn:aws:iotanalytics:us-west-2:123456789012:datastore/datastore_IoTSiteWise_demo",
      "retentionPeriod": {
          "numberOfDays": 90,
          "unlimited": false
      }
  }
```

# Troubleshoot storage settings for Amazon IoT SiteWise
Troubleshoot storage settings

Use the following information to troubleshoot and resolve issues with the storage configuration.

**Topics**
+ [

## Error: Bucket doesn't exist
](#no-s3-bucket)
+ [

## Error: Access denied to Amazon S3 path
](#iam-permissions)
+ [

## Error: Role ARN can't be assumed
](#iam-trust-relationship)
+ [

## Error: Failed to access cross-Region Amazon S3 bucket
](#cross-region-s3-bucket)

## Error: Bucket doesn't exist


**Solution:** Amazon IoT SiteWise couldn't find your Amazon S3 bucket. Make sure you enter the name of an existing Amazon S3 bucket in the current Region.

## Error: Access denied to Amazon S3 path


**Solution:** Amazon IoT SiteWise couldn't access your Amazon S3 bucket. Do the following:
+ Make sure that you use the same Amazon S3 bucket that you specified in the IAM policy.
+ Make sure that your role has the permissions shown in the following example.  
**Example permissions policy**  

------
#### [ JSON ]

****  

  ```
  {
        "Version":"2012-10-17",		 	 	 
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "s3:PutObject",
                    "s3:GetObject",
                    "s3:DeleteObject",
                    "s3:GetBucketLocation",
                    "s3:ListBucket"
                ],
                "Resource": [
                    "arn:aws-cn:s3:::amzn-s3-demo-bucket",
                    "arn:aws-cn:s3:::amzn-s3-demo-bucket/*"
                ]
            }
        ]
    }
  ```

------

  Replace amzn-s3-demo-bucket with the name of your Amazon S3 bucket.

## Error: Role ARN can't be assumed


**Solution:** Amazon IoT SiteWise couldn't assume the IAM role on your behalf. Make sure that your role trusts the following service: `iotsitewise.amazonaws.com`. For more information, see [I can't assume a role](https://docs.amazonaws.cn/IAM/latest/UserGuide/troubleshoot_roles.html#troubleshoot_roles_cant-assume-role) see *IAM User Guide*.

## Error: Failed to access cross-Region Amazon S3 bucket


**Solution:** The Amazon S3 bucket that you specified is in a different Amazon Region. Make sure that your Amazon S3 bucket and Amazon IoT SiteWise assets are in the same Region.

# File paths and schemas of data saved in the cold tier


Amazon IoT SiteWise stores your data in the cold tier by replicating time series, including measurements, metrics, transforms and aggregates, and also asset and asset model definitions. The following describes the file paths and schemas of data that is sent to the cold tier.

**Topics**
+ [

## Equipment data (measurements)
](#measurements-file-path-and-schema)
+ [

## Metrics, transforms, and aggregates
](#metrics-file-path-and-schema)
+ [

## Asset metadata
](#asset-metadata)
+ [

## Asset hierarchy metadata
](#asset-hierarchy-metadata)
+ [

## Storage data index files
](#storage-data-index)

## Equipment data (measurements)


Amazon IoT SiteWise exports equipment data (measurements) to the cold tier once every six hours. Raw data is saved in the cold tier in the [Apache AVRO](https://avro.apache.org) (`.avro`) format.

### File path


Amazon IoT SiteWise stores equipment data (measurements) in the cold tier using the following template.

```
{keyPrefix}/raw/startYear={startYear}/startMonth={startMonth}/startDay={startDay}/seriesBucket={seriesBucket}/raw_{timeseriesId}_{startTimestamp}_{quality}.avro
```

Every file path to raw data in Amazon S3 contains the following components.

#### File path



| Path component | Description | 
| --- | --- | 
|  `keyPrefix`  |  The Amazon S3 prefix that you specified in the Amazon IoT SiteWise storage configuration. Amazon S3 uses the prefix as a folder name in the bucket.  | 
|  `raw`  |  The folder that stores time series data from equipment (measurements). The `raw` folder is saved in the prefix folder.  | 
|  `seriesBucket`  |  A hexadecimal number between 00 and ff. This number is derived from `timeSeriesId`. This partition is used to increase throughput when Amazon IoT SiteWise writes to the cold tier. When you use Amazon Athena to run queries, you can use the partition for fine-grain partitioning to improve query performance. `seriesBucket` and `timeSeriesBucket` in the asset metadata are the same number.  | 
|  `startYear`  |  The year of the exclusive start time associated with the time series data.  | 
|  `startMonth`  |  The month of the exclusive start time associated with the time series data.  | 
|  `startDay`  |  The day of the month of the exclusive start time associated with the time series data.  | 
|  `fileName`  |  The file name uses the underscore (\$1) character as a delimiter to separate the following: [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/iot-sitewise/latest/userguide/file-path-and-schema.html) The file is saved in the `.avro` format by using the [Snappy](https://github.com/google/snappy) compression.  | 

**Example file path to raw data in the cold tier**  
`keyPrefix/raw/startYear=2021/startMonth=1/startDay=2/seriesBucket=a2/raw_7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a_1609577700_GOOD.avro`

### Fields


The schema of raw data that is exported to the cold tier contains the following fields.

 Amazon IoT SiteWise advises customers to implement support for schema evolution on systems that read raw data from cold tier, as there may be additional fields introduced in the future.

 Null data is represented as all value fields being null. However, customers will still receive the correct data type when querying with Amazon IoT SiteWise APIs. 

#### Fields



| Field name | Supported types | Default type | Description | 
| --- | --- | --- | --- | 
|  `seriesId`  |  `string`  |  N/A  |  The ID that identifies the time series data from equipment (measurements). You can use this field to join raw data and asset metadata in queries.  | 
|  `timeInSeconds`  |  `long`  |  N/A  |  The timestamp date, in seconds, in the Unix epoch format. Fractional nanosecond data is provided by `offsetInNanos`.  | 
|  `offsetInNanos`  |  `long`  |  N/A  |  The nanosecond offset from `timeInSeconds`.  | 
|  `quality`  |  `string`  |  N/A  |  The quality of the time series value.  | 
|  `doubleValue`  |  `double` or `null`  |  `null`  |  Time series data of type double (floating point number).  | 
|  `stringValue`  |  `string` or `null`  |  `null`  |  Time series data of type string (sequence of characters).  | 
|  `integerValue`  |  `int` or `null`  |  `null`  |  Time series data of type integer (whole number).  | 
|  `booleanValue`  |  `boolean` or `null`  |  `null`  |  Time series data of type Boolean (true or false).  | 
|  `jsonValue`  |  `string` or `null`  |  `null`  |  Time series data of type JSON (complex data types stored as a string).  | 
|  `recordVersion`  |  `long` or `null`  |  `null`  |  The version number for the record. You can use the version number to select the latest record. Newer records have larger version numbers.  | 

**Example raw data in the cold tier**  

```
  {"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675887,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.75},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
  {"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675889,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.69},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
  {"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675890,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.66},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
  {"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675891,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.92},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
  {"seriesId":"e9687d2a-0dbe-4f65-9ed6-6f443cba41f7_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeInSeconds":1625675892,"offsetInNanos":0,"quality":"GOOD","doubleValue":{"double":0.73},"stringValue":null,"integerValue":null,"booleanValue":null,"jsonValue":null,"recordVersion":null}
```

## Metrics, transforms, and aggregates


Amazon IoT SiteWise exports metrics, transforms, and aggregates to the cold tier once every six hours. Metrics, transforms, and aggregates are saved in the cold tier in the [Apache AVRO](https://avro.apache.org) (`.avro`) format.

### File path


Amazon IoT SiteWise stores metrics, transforms, and aggregates in the cold tier using the following template.

```
{keyPrefix}/agg/startYear={startYear}/startMonth={startMonth}/startDay={startDay}/seriesBucket={seriesBucket}/agg_{timeseriesId}_{startTimestamp}_{quality}.avro
```

Every file path to metrics, transforms, and aggregates in Amazon S3 contains the following components.

#### File path



| Path component | Description | 
| --- | --- | 
|  `keyPrefix`  |  The Amazon S3 prefix that you specified in the Amazon IoT SiteWise storage configuration. Amazon S3 uses the prefix as a folder name in the bucket.  | 
|  `agg`  |  The folder that stores time series data from metrics. The `agg` folder is saved in the prefix folder.  | 
|  `seriesBucket`  |  A hexadecimal number between 00 and ff. This number is derived from `timeSeriesId`. This partition is used to increase throughput when Amazon IoT SiteWise writes to the cold tier. When you use Amazon Athena to run queries, you can use the partition for fine-grain partitioning to improve query performance. `seriesBucket` and `timeSeriesBucket` in the asset metadata are the same number.  | 
|  `startYear`  |  The year of the exclusive start time associated with the time series data.  | 
|  `startMonth`  |  The month of the exclusive start time associated with the time series data.  | 
|  `startDay`  |  The day of the month of the exclusive start time associated with the time series data.  | 
|  `fileName`  |  The file name uses the underscore (\$1) character as a delimiter to separate the following: [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/iot-sitewise/latest/userguide/file-path-and-schema.html) The file is saved in the `.avro` format by using the [Snappy](https://github.com/google/snappy) compression.  | 

**Example file path to metrics in the cold tier**  
`keyPrefix/agg/startYear=2021/startMonth=1/startDay=2/seriesBucket=a2/agg_7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a_1609577700_GOOD.avro`

### Fields


The schema of metrics, transforms, and aggregates that are exported to the cold tier contains the following fields.

#### Fields



| Field name | Supported types | Default type | Description | 
| --- | --- | --- | --- | 
|  `seriesId`  |  `string`  |  N/A  |  The ID that identifies the time series data from equipment, metrics, or transforms. You can use this field to join raw data and asset metadata in queries.  | 
|  `timeInSeconds`  |  `long`  |  N/A  |  The timestamp date, in seconds, in the Unix epoch format. Fractional nanosecond data is provided by `offsetInNanos`.  | 
|  `offsetInNanos`  |  `long`  |  N/A  |  The nanosecond offset from `timeInSeconds`.  | 
|  `quality`  |  `string`  |  N/A  |  The quality by which to filter asset data.  | 
|  `resolution`  |  `string`  |  N/A  |  The time interval over which to aggregate data.  | 
|  `count`  |  `double` or `null`  |  `null`  |  The total number of data points for the given variables over the current time interval.  | 
|  `average`  |  `double` or `null`  |  `null`  |  The mean of the given variables' values over the current time interval.  | 
|  `min`  |  `double` or `null`  |  `null`  |  The minimum of the given variables' values over the current time interval.  | 
|  `max`  |  `boolean` or `null`  |  `null`  |  The maximum of the given variables' values over the current time interval.  | 
|  `sum`  |  `string` or `null`  |  `null`  |  The sum of the given variables' values over the current time interval.  | 
|  `recordVersion`  |  `long` or `null`  |  `null`  |  The version number for the record. You can use the version number to select the latest record. Newer records have larger version numbers.  | 

**Example Metric data in the cold tier**  

```
{"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637334060,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":31.0,"average":{"double":16.0},"min":{"double":1.0},"max":{"double":31.0},"sum":{"double":496.0},"recordVersion":null}
  {"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637334120,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":29.0,"average":{"double":46.0},"min":{"double":32.0},"max":{"double":60.0},"sum":{"double":1334.0},"recordVersion":null}
  {"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637334540,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":31.0,"average":{"double":16.0},"min":{"double":1.0},"max":{"double":31.0},"sum":{"double":496.0},"recordVersion":null}
  {"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637334600,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":29.0,"average":{"double":46.0},"min":{"double":32.0},"max":{"double":60.0},"sum":{"double":1334.0},"recordVersion":null}
  {"seriesId":"f74c2828-5317-4df3-ba16-6d41b5bcb531","timeInSeconds":1637335020,"offsetInNanos":0,"quality":"GOOD","resolution":"PT1M","count":31.0,"average":{"double":16.0},"min":{"double":1.0},"max":{"double":31.0},"sum":{"double":496.0},"recordVersion":null}
```

## Asset metadata


When you enable Amazon IoT SiteWise to export data to the cold tier for the first time, asset metadata is exported to the cold tier. After the initial configuration, Amazon IoT SiteWise exports asset metadata to the tier only when you change asset model definitions or asset definitions. Asset metadata is saved in the cold tier in the newline delimited JSON (`.ndjson`) format.

### File path


Amazon IoT SiteWise stores asset metadata in the cold tier using the following template.

```
{keyPrefix}/asset_metadata/asset_{assetId}.ndjson
```

Every file path to asset metadata in the cold tier contains the following components.

#### File path



| Path component | Description | 
| --- | --- | 
|  `keyPrefix`  |  The Amazon S3 prefix that you specified in the Amazon IoT SiteWises storage configuration. Amazon S3 uses the prefix as a folder name in the bucket.  | 
|  `asset_metadata`  |  The folder that stores asset metadata. The `asset_metadata` folder is saved in the prefix folder.  | 
|  `fileName`  |  The file name uses the underscore (\$1) character as a delimiter to separate the following: [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/iot-sitewise/latest/userguide/file-path-and-schema.html) The file is saved in the `.ndjson` format.  | 

**Example file path to asset metadata in the colder tier**  
`keyPrefix/asset_metadata/asset_35901915-d476-4dca-8637-d9ed4df939ed.ndjson`

### Fields


The schema of asset metadata that is exported to the cold tier contains the following fields.

#### Fields



| Field name | Description | 
| --- | --- | 
|  `assetId`  |  The ID of the asset.  | 
|  `assetName`  |  The name of the asset.  | 
|  `assetExternalId`  |  The external ID of the asset.  | 
|  `assetModelId`  |  The ID of the asset model used to create this asset.  | 
|  `assetModelName`  |  The name of the asset model.  | 
|  `assetModelExternalId`  |  The external ID of the asset model.  | 
|  `assetPropertyId`  |  The ID of the asset property.  | 
|  `assetPropertyName`  |  The name of the asset property.  | 
|  `assetPropertyExternalId`  |  The external ID of the asset property.  | 
|  `assetPropertyDataType`  |  The data type of the asset property.  | 
|  `assetPropertyUnit`  |  The unit of the asset property (for example, `Newtons` and `RPM`).  | 
|  `assetPropertyAlias`  |  The alias that identifies the asset property, such as an OPC UA server data stream path (for example, `/company/windfarm/3/turbine/7/temperature`).  | 
|  `timeSeriesId`  |  The ID that identifies the time series data from equipment, metrics, or transforms. You can use this field to join raw data and asset metadata in queries.  | 
|  `timeSeriesBucket`  |  A hexadecimal number between 00 and ff. This number is derived from `timeSeriesId`. This partition is used to increase throughput when Amazon IoT SiteWise writes to the cold tier. When you use Amazon Athena to run queries, you can use the partition for fine-grain partitioning to improve query performance. `timeSeriesBucket` and `seriesBucket` in the file path to raw data are the same number.  | 
|  `assetCompositeModelId`  |  The ID of the composite model.  | 
|  `assetCompositeModelExternalId`  |  The external ID of the composite model.  | 
|  `assetCompositeModelDescription`  |  The description of the composite model.  | 
|  `assetCompositeModelName`  |  The name of the composite model.  | 
|  `assetCompositeModelType`  |  The type of the composite model. For alarm composite models, this type is `AWS/ALARM`.  | 
|  `assetCreationDate`  |  The date the asset was created, in Unix epoch time.  | 
|  `assetLastUpdateDate`  |  The date the asset was last updated, in Unix epoch time.  | 
|  `assetStatusErrorCode`  |  The error code.  | 
|  `assetStatusErrorMessage`  |  The error message.  | 
|  `assetStatusState`  |  The current status of the asset.  | 

**Example asset metadata in the cold tier**  

```
  {"assetId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d","assetExternalId":null,"assetName":"Wind Turbine Asset 2","assetModelId":"ec1d924f-f07d-444f-b072-e2994c165d35","assetModelExternalId":null,"assetModelName":"Wind Turbine Asset Model","assetPropertyId":"95e63da7-d34e-43e1-bc6f-1b490154b07a","assetPropertyExternalId":null,"assetPropertyName":"Temperature","assetPropertyDataType":"DOUBLE","assetPropertyUnit":"Celsius","assetPropertyAlias":"USA/Washington/Seattle/WT2/temp","timeSeriesId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a","timeSeriesBucket":"f6","assetArn":null,"assetCompositeModelDescription":null,"assetCompositeModelName":null,"assetCompositeModelType":null,"assetCompositeModelId":null,"assetCompositeModelExternalId":null,"assetCreationDate":1619466323,"assetLastUpdateDate":1623859856,"assetStatusErrorCode":null,"assetStatusErrorMessage":null,"assetStatusState":"ACTIVE"}
  {"assetId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d","assetExternalId":null,"assetName":"Wind Turbine Asset 2","assetModelId":"ec1d924f-f07d-444f-b072-e2994c165d35","assetModelExternalId":null,"assetModelName":"Wind Turbine Asset Model","assetPropertyId":"c706d54d-4c11-42dc-9a01-63662fc697b4","assetPropertyExternalId":null,"assetPropertyName":"Pressure","assetPropertyDataType":"DOUBLE","assetPropertyUnit":"KiloPascal","assetPropertyAlias":"USA/Washington/Seattle/WT2/pressure","timeSeriesId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d_c706d54d-4c11-42dc-9a01-63662fc697b4","timeSeriesBucket":"1e","assetArn":null,"assetCompositeModelDescription":null,"assetCompositeModelName":null,"assetCompositeModelType":null,"assetCompositeModelId":null,"assetCompositeModelExternalId":null,"assetCreationDate":1619466323,"assetLastUpdateDate":1623859856,"assetStatusErrorCode":null,"assetStatusErrorMessage":null,"assetStatusState":"ACTIVE"}
  {"assetId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d","assetExternalId":null,"assetName":"Wind Turbine Asset 2","assetModelId":"ec1d924f-f07d-444f-b072-e2994c165d35","assetModelExternalId":null,"assetModelName":"Wind Turbine Asset Model","assetPropertyId":"8cf1162f-dead-4fbe-b468-c8e24cde9f50","assetPropertyExternalId":null,"assetPropertyName":"Max Temperature","assetPropertyDataType":"DOUBLE","assetPropertyUnit":null,"assetPropertyAlias":null,"timeSeriesId":"7020c8e2-e6db-40fa-9845-ed0dddd4c77d_8cf1162f-dead-4fbe-b468-c8e24cde9f50","timeSeriesBucket":"d7","assetArn":null,"assetCompositeModelDescription":null,"assetCompositeModelName":null,"assetCompositeModelType":null,"assetCompositeModelId":null,"assetCompositeModelExternalId":null,"assetCreationDate":1619466323,"assetLastUpdateDate":1623859856,"assetStatusErrorCode":null,"assetStatusErrorMessage":null,"assetStatusState":"ACTIVE"}
  {"assetId":"3a5f2a22-3b37-4332-9c1c-404ea1d73fab","assetExternalId":null,"assetName":"BatchAssetDouble1","assetModelId":"814bdfd8-24db-4a33-8d9b-ebc75e75e827","assetModelExternalId":null,"assetModelName":"FlashTestAssetModelDouble","assetPropertyId":"6b7e1532-175b-4c02-b410-ab401a9176ed","assetPropertyExternalId":null,"assetPropertyName":"measurementProperty","assetPropertyDataType":"DOUBLE","assetPropertyUnit":"u","assetPropertyAlias":null,"timeSeriesId":"ab19f4fa-7e7b-4247-ae89-ff316f5ff8aa","timeSeriesBucket":"af","assetArn":null,"assetCompositeModelDescription":null,"assetCompositeModelName":null,"assetCompositeModelType":null,"assetCompositeModelId":null,"assetCompositeModelExternalId":null,"assetCreationDate":1646960106,"assetLastUpdateDate":1646960106,"assetStatusErrorCode":null,"assetStatusErrorMessage":null,"assetStatusState":"ACTIVE"}
```

## Asset hierarchy metadata


When you enable Amazon IoT SiteWise to save data the in cold tier for the first time, asset hierarchy metadata is exported to the cold tier. After the initial configuration, Amazon IoT SiteWise exports asset hierarchy metadata to the cold tier only when you make changes to asset model or asset definitions. Asset hierarchy metadata is saved in the cold tier in the newline delimited JSON (`.ndjson`) format.

An external identifier for the hierarchy, target asset, or source asset is retrieved by calling the [DescribeAsset](https://docs.amazonaws.cn/iot-sitewise/latest/APIReference/API_DescribeAsset.html) API. 

### File path


Amazon IoT SiteWise stores asset hierarchy metadata in the cold tier using the following template.

```
{keyPrefix}/asset_hierarchy_metadata/{parentAssetId}_{hierarchyId}.ndjson
```

Every file path to asset hierarchy metadata in the cold tier contains the following components.

#### File path



| Path component | Description | 
| --- | --- | 
|  `keyPrefix`  |  The Amazon S3 prefix that you specified in the Amazon IoT SiteWise storage configuration. Amazon S3 uses the prefix as a folder name in the bucket.  | 
|  `asset_hierarchy_metadata`  |  The folder that stores asset hierarchy metadata. The `asset_hierarchy_metadata` folder is saved in the prefix folder.  | 
|  `fileName`  |  The file name uses the underscore (\$1) character as a delimiter to separate the following: [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/iot-sitewise/latest/userguide/file-path-and-schema.html) The file is saved in the `.ndjson` format.  | 

**Example file path to asset hierarchy metadata in the cold tier**  
`keyPrefix/asset_hierarchy_metadata/35901915-d476-4dca-8637-d9ed4df939ed_c5b3ced8-589a-48c7-9998-cdccfc9747a0.ndjson`

### Fields


The schema of asset hierarchy metadata that is exported to the cold tier contains the following fields.

#### Fields



| Field name | Description | 
| --- | --- | 
|  `sourceAssetId`  |  The ID of the source asset in this asset relationship.  | 
|  `targetAssetId`  |  The ID of the target asset in this asset relationship.  | 
|  `hierarchyId`  |  The ID of the hierarchy.  | 
|  `associationType`  |  The association type of this asset relationship.  The value must be `CHILD`. The target asset is a child asset of the source asset.  | 

**Example asset hierarchy metadata in the cold tier**  

```
{"sourceAssetId":"80388e72-2284-44fb-9c89-bfbaf0dfedd2","targetAssetId":"2b866c25-0c74-4750-bdf5-b73683c8a2a2","hierarchyId":"bbed9f59-0412-4585-a61d-6044db526aee","associationType":"CHILD"}
  {"sourceAssetId":"80388e72-2284-44fb-9c89-bfbaf0dfedd2","targetAssetId":"6b51246e-984d-460d-bc0b-470ea47d1e31","hierarchyId":"bbed9f59-0412-4585-a61d-6044db526aee","associationType":"CHILD"}
```

**To view your data in the cold tier**

1. Navigate to the [Amazon S3 console](https://console.amazonaws.cn/s3/).

1. In the navigation pane, choose **Buckets**, and then choose your Amazon S3 bucket.

1. Navigate to the folder that contains the raw data, asset metadata, or asset hierarchy metadata.

1. Select the files, and then from **Actions**, choose **Download**.

## Storage data index files


Amazon IoT SiteWise uses these files to optimize data query performance. They appear in your Amazon S3 bucket, but you don't need to use them.

### File path


Amazon IoT SiteWise stores data index files in the cold tier using the following template.

```
keyPrefix/index/series=timeseriesId/startYear=startYear/startMonth=startMonth/startDay=startDay/index_timeseriesId_startTimestamp_quality
```

**Example file path to data storage index file**  
`keyPrefix/index/series=7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a/startYear=2022/startMonth=02/startDay=03/index_7020c8e2-e6db-40fa-9845-ed0dddd4c77d_95e63da7-d34e-43e1-bc6f-1b490154b07a_1643846400_GOOD`