> This page is for Data Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.eon.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.eon.io/_mcp/server. # Query Database Snapshots This article explains how to query your database snapshots in the Eon console and through the API. ## Query a database snapshot #### With the Eon console To get started, open the database you want to query in the database explorer. You can do this from either your inventory or the Search page: * **In your inventory**: Select the database resource, and click **Explore database** when the drawer opens. * **In the Search page**: Search for a database name, table name, or column, and click **Explore Database** in the relevant card in the results. #### Before you start * You can query only RDS databases that are backed up by Eon. If your database hasn't been backed up by Eon, or if all its Eon snapshots have expired, you can back it up on demand. * Make sure the restore account contains a bucket in the same region as the vault you're querying from. #### Choose the snapshot you want to query In the database explorer, under **Currently exploring this snapshot**, check the time and date of the snapshot you're exploring. This is the snapshot you'll query. If you want to query a different snapshot: 1. Click **Change**. You'll see a calendar view with colored dots on the days when snapshots were taken. There can be more than one snapshot per day. When you click a day, a list of database snapshots taken that day is displayed below the calendar. 2. When you find the snapshot you want to explore, click **Select**. The database explorer updates to show the snapshot you selected. 3. The schema is presented as a tree view that shows the database structure when the snapshot was taken. You can expand all the levels to see your tables and columns. #### Choose the database to query If the resource backed up by the snapshot contains multiple databases, you'll choose which database to query. To do this, click the **Querying database** list and select the database you want to query. #### Choose the restore storage destination Query results are restored to a bucket in your restore account. To set the destination bucket: 1. Click **Save results to**. The **Save Destination** drawer opens. 2. Choose an **Account** and **Bucket**. 3. Optionally, you can provide a bucket **Prefix** if you want to restore the object to a specific location in the bucket. If you don't provide a prefix, the object is restored to the bucket root. > **Warning** > > If there are naming conflicts with existing objects, Eon overwrites the existing data. > We recommend using a prefix if you're restoring to a non-empty bucket. 4. Click **Save**. #### Run the query Eon supports running `SELECT` SQL queries against snapshots as if you were querying the original database directly. Under the hood, Eon queries the snapshot data with Amazon Athena. For more information, see [SELECT] in the Amazon Athena docs. [SELECT]: https\://docs.aws.amazon.com/athena/latest/ug/select.html To query the snapshot, enter your SQL expression in the query editor, and click **Run Query**. The query runs and, when the response is ready, a sample of the results is displayed in the results panel. Note that the sample results are limited to 1,000 rows. #### Download the records When you run a query, the full results are saved to the restore bucket as a CSV file. If you need to see more than 1,000 records or share the results, you can retrieve the CSV file by clicking (Visit object URL) or (Visit object URL). Note that read access to the S3 bucket is needed to visit the URL or download the file. > **Info** > > If you navigated away from the database explorer before the query results were returned, the location of the query results won't be displayed in the console. > You can still retrieve them by visiting the restore bucket at the prefix you specified in step 3. #### With the API Querying a database snapshot with the Eon API is an asynchronous operation that involves three methods: [Run Query], [Get Query Status], and [Get Query Result]. When you call Run Query, you'll receive a query ID in response. You can then use the query ID to check the query status and retrieve the result. This procedure covers the typical flow for running a query through the Eon API. > **Info** > > The methods covered here are documented in [Database Snapshots] in the API reference. [Database Snapshots]: /api/api-reference/query-databases[Run Query]: /api/api-reference/query-databases/run-query[Get Query Status]: /api/api-reference/query-databases/get-query-status[Get Query Result]: /api/api-reference/query-databases/get-query-result #### Before you start * You can query only RDS databases that are backed up by Eon. If your database hasn't been backed up by Eon, or if all its Eon snapshots have expired, you can back it up on demand. * Make sure the restore account contains a bucket with a bucket policy that grants write access to Eon. See \[Set Up Granular Restore Storage] for more information. #### Run the query Call Run Query, providing your SQL query in the `query` body parameter. This table gives some guidance for the remaining paremeters: | In | Parameter | Where to get the value | | ---- | ------------------ | ---------------------------------------------------------------------------- | | Path | `projectId` | API Credentials page in the Eon console. | | | `snapshotId` | [List Resource Snapshots] through the Eon API. | | Body | `databaseName` | Eon database explorer or accessing the database through your cloud provider. | | | `restoreAccountId` | [List Restore Accounts] through the Eon API. | | | `destination` | See your list of S3 buckets in the AWS management console. | A query ID is returned for a successful request. Use the query ID to check the query status in the next step. #### Code examples **`Example request`** ```bash title="Example request" curl -L 'https://{your_eon_subdomain}/api/v1/projects/{projectId}/snapshots/{snapshotId}/databases/query' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {access_token}' \ -d '{ "databaseName": "postgres", "query": "SELECT * FROM customers LIMIT 50", "restoreAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "destination": { "s3Bucket": { "bucketName": "my-us-east-restore-bucket", "prefix": "db_queries" } } }' ``` **`Response`** ```json title="Response" { "queryId": "c951704d-81f7-58b5-8c42-3056bad80f7a" } ``` [List Resource Snapshots]: /api/api-reference/backup-management/snapshots/list-resource-snapshots[List Restore Accounts]: /api/api-reference/restore-connections/restore-accounts/list-restore-accounts[Troubleshooting Queries]: /data-protection/backup-and-protection/exploring-and-querying/query/troubleshooting-queries #### Check the query status Using the query ID returned in the previous step, call Get Query Status to check the status of the query. If the query is in progress, you can periodically poll Get Query Status until the query is either completed or failed. Once the query is done running, it has a status of `COMPLETED`. The response object contains `outputLocation`, which is a URI where a CSV of the query results can be downloaded. Note that the URI is the destination bucket and prefix you passed in the previous request. If the query failed, it has a status of `FAILED`. See [Troubleshooting Queries] for possible errors and how to resolve them. #### Code examples **`Example request`** ```bash title="Example request" curl -L 'https://{your_eon_subdomain}/api/v1/projects/{projectId}/queries/{queryId}/status' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {access_token}' ``` **`Example response`** ```json title="Example response" { "status": "COMPLETED", "outputLocation": "s3://my-us-east-restore-bucket/db_queries/c951704d-81f7-58b5-8c42-3056bad80f7a.csv" } ``` #### Retrieve the query results Using the query ID from step 1, call Get Query Result to retrieve paginated query results through the API. The response object contains two properties: `columns` and `records`: * `columns` is an array of strings, which you can use to display the column names. * `records` is an array of arrays. Each inner array represents a row of records, with the values in the same order as the column names. Values are converted to strings, regardless of the original data type. If the response contains `nextToken`, there are more records available. You can retrieve them by calling Get Query Result again, setting the `pageToken` query parameter as the value returned in `nextToken`. See [Pagination] for more information on how to work with paginated results. [Pagination]: /api/using-the-api/pagination #### Code examples **`Example request`** ```bash title="Example request" curl -L 'https://{your_eon_subdomain}/api/v1/projects/{projectId}/queries/{queryId}/results' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {access_token}' ``` **`Example response`** ```json title="Example response" { "columns": [ "id", "first_name", "last_name", "email" ], "records": [ ["1", "Brandi", "Donovan", "brandi.donovan@example.com"], ["2", "Curtis", "Brooks", "curtis.brooks@example.com"], ["3", "Shawn", "Ray", "shawn.ray@example.com"], ["4", "Brooke", "Reyes", "brooke.reyes@example.com"], ["5", "Kellie", "Hanson", "kellie.hanson@example.com"], ["6", "Gordon", "Pena", "gordon.pena@example.com"], ["7", "Chelsey", "Lyons", "chelsey.lyons@example.com"], ["8", "Cindy", "Ramsey", "cindy.ramsey@example.com"], ["9", "Jasmine", "Alexander", "jasmine.alexander@example.com"], ["10", "Amanda", "Krueger", "amanda.krueger@example.com"], ["11", "Desiree", "Brown", "desiree.brown@example.com"], ["12", "Howard", "Phelps", "howard.phelps@example.com"], ["13", "David", "Collins", "david.collins@example.com"], ["14", "Robert", "Rosales", "robert.rosales@example.com"], ["15", "Shane", "Adams", "shane.adams@example.com"], ["16", "Jeffrey", "Gordon", "jeffrey.gordon@example.com"], ["17", "Ronald", "Braun", "ronald.braun@example.com"], ["18", "Nancy", "Hanson", "nancy.hanson@example.com"], ["19", "Lisa", "Singh", "lisa.singh@example.com"], ["20", "Sarah", "Brooks", "sarah.brooks@example.com"], ["21", "Jeffery", "Camacho", "jeffery.camacho@example.com"], ["22", "Anna", "Lee", "anna.lee@example.com"], ["23", "Roger", "Hines", "roger.hines@example.com"], ["24", "Lori", "Morris", "lori.morris@example.com"], ["25", "Jason", "Martin", "jason.martin@example.com"], ["26", "Francisco", "Townsend", "francisco.townsend@example.com"], ["27", "Stephen", "Leonard", "stephen.leonard@example.com"], ["28", "Jay", "Wilson", "jay.wilson@example.com"], ["29", "David", "Hebert", "david.hebert@example.com"], ["30", "Dennis", "Lawson", "dennis.lawson@example.com"], ["31", "Kerry", "Page", "kerry.page@example.com"], ["32", "Amanda", "Edwards", "amanda.edwards@example.com"], ["33", "Catherine", "Delacruz", "catherine.delacruz@example.com"], ["34", "Jennifer", "Russell", "jennifer.russell@example.com"], ["35", "Christine", "Yang", "christine.yang@example.com"], ["36", "Amanda", "Sparks", "amanda.sparks@example.com"], ["37", "Randy", "Singleton", "randy.singleton@example.com"], ["38", "Latoya", "Flores", "latoya.flores@example.com"], ["39", "Kellie", "Landry", "kellie.landry@example.com"], ["40", "Katie", "Johnson", "katie.johnson@example.com"], ["41", "Mary", "Cochran", "mary.cochran@example.com"], ["42", "Chris", "Mcknight", "chris.mcknight@example.com"], ["43", "John", "Hill", "john.hill@example.com"], ["44", "Xavier", "Gomez", "xavier.gomez@example.com"], ["45", "Alexander", "Dodson", "alexander.dodson@example.com"], ["46", "Robert", "Sims", "robert.sims@example.com"], ["47", "Sydney", "Nelson", "sydney.nelson@example.com"], ["48", "Emily", "Conway", "emily.conway@example.com"], ["49", "Paul", "Adkins", "paul.adkins@example.com"], ["50", "Kurt", "Manning", "kurt.manning@example.com"] ] } ``` You can now share or download the query results as needed. Additionally, Eon creates a restore job for the query, which you can find in the Restore jobs tab in the Jobs page. ## See also * [About Querying](/data-protection/backup-and-protection/exploring-and-querying/query/about-querying) * [Troubleshooting Queries](/data-protection/backup-and-protection/exploring-and-querying/query/troubleshooting-queries) * [API reference: Database Snapshots][Database Snapshots]