---
title: Query Translation
description: >-
  Translate Splunk SPL queries into Datadog syntax and convert Splunk alerts and
  dashboards into Datadog monitors and dashboards.
breadcrumbs: Docs > Log Management > Migration > Query Translation
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Query Translation

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

## Overview{% #overview %}

Query Translation, part of the Migration App, translates Splunk Processing Language (SPL) into Datadog [log search syntax](https://docs.datadoghq.com/logs/explorer/search_syntax.md) and converts Splunk assets into their Datadog equivalents. It provides two tools:

| Tool                                                                    | Use case                                                                                                                                                                            |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Translate](https://app.datadoghq.com/logs/query-translator/translator) | Translate a single SPL query and see the Datadog equivalent with an explanation of the translation.                                                                                 |
| [Import](https://app.datadoghq.com/logs/batch-migration)                | Import CSV exports of Splunk alerts and dashboards, and translate their queries to log search syntax. Review the results, then create the matching Datadog monitors and dashboards. |

Query Translation supports only Splunk as a source platform. It parses and converts queries deterministically with translation libraries, not a large language model. Each query is translated into [log search syntax](https://docs.datadoghq.com/logs/explorer/search_syntax.md) when possible for use with the Log Explorer, log monitors, and dashboard widgets. Analytically complex queries that log search syntax cannot express fall back to [DDSQL](https://docs.datadoghq.com/ddsql_editor.md).

## Permissions{% #permissions %}

Importing Splunk assets requires the `logs_read_config` permission. Publishing a translated resource also requires the permission for the asset being created: `monitors_write` for monitors, and `dashboards_write` for dashboards. See [Datadog Role Permissions](https://docs.datadoghq.com/account_management/rbac/permissions.md).

## Translate a single query{% #translate-a-single-query %}

Use the Translate page as a sandbox for SPL. It is designed for exploring translation behavior rather than for migrating an inventory of assets.

1. Go to [Logs > Translate](https://app.datadoghq.com/logs/query-translator/translator).
1. Paste an SPL query into the query box, or select one of the provided examples.
1. Click Translate.

The page returns:

- **Translated query**: The Datadog query, in log search syntax or DDSQL, shown in the search bar above the Translation preview chart.
- Translation preview: The data matching the translated query, over a time range you specify. Click View in Log Explorer to continue in the [Log Explorer](https://docs.datadoghq.com/logs/explorer.md).
- Translated SPL: Your original SPL, annotated with anything the translator changed or could not translate, such as stripped indexes or unsupported commands.
- How did we translate?: An explanation of which SPL command maps to which part of the Datadog query.

To build a monitor on the translated query, click Create Monitor.

## Migrate assets in bulk{% #migrate-assets-in-bulk %}

The Import page migrates many Splunk assets at once. You upload your Splunk inventory as CSV files, and the tool groups them into a named import. It translates the queries in each asset to Datadog syntax and builds the matching Datadog monitor or dashboard. You review each result, then publish it to create the asset in Datadog. The following resource types are supported:

| Splunk resource      | Datadog equivalent                                          | Notes                                                                                                                                                                 |
| -------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alert (saved search) | [Monitor](https://docs.datadoghq.com/monitors/types/log.md) | Translates to a log monitor when possible. Otherwise, it translates to an analysis monitor with a DDSQL query.                                                        |
| Dashboard            | [Dashboard](https://docs.datadoghq.com/dashboards.md)       | Both Studio (JSON) and Classic (XML) dashboards are supported. Each panel is translated into a separate widget.                                                       |
| Search macro         | None                                                        | Before translation, the tool replaces each macro reference in your alerts and dashboards with the macro's SPL definition. Macros are not published as Datadog assets. |

### Export your assets from Splunk{% #export-your-assets-from-splunk %}

Export each resource type from Splunk as a separate CSV file:

1. Sign in to Splunk and open the Search app.

1. Run the query for the resource type you want to export:

Alerts:

   ```
   | rest /services/saved/searches splunk_server=local
   | table
     title
     eai:acl.owner
     eai:acl.app
     search
     triggered_alert_count
     alert_condition
     alert_threshold
     alert_comparator
     alert_type
     actions
     action.email.to
     action.email.message.alert
     action.slack.param.channel
     action.slackparam.message
     description
   ```

Dashboards:

   ```zed
   | rest /servicesNS/admin/search/data/ui/views
   | spath input=eai:data path=dashboard.definition output=definition
   | spath input=eai:data path=dashboard output=dashboard_xml
   | where isnotnull(definition) OR (isnull(definition) AND isnotnull(dashboard_xml))
   | eval result=if(isnotnull(definition), definition, 'eai:data')
   | eval type=if(isnotnull(definition), "studio", "legacy")
   | eval title=if(type=="studio", json_extract(result, "title"), null())
   | eval description=if(type=="studio", json_extract(result, "description"), null())
   | spath input=result path=dashboard.label output=xml_title
   | spath input=result path=dashboard.description output=xml_description
   | eval title=coalesce(title, xml_title)
   | eval description=coalesce(description, xml_description)
   | fields type,title,description,result
   ```

Macros:

   ```zed
   | rest /servicesNS/-/-/admin/macros count=0 splunk_server=local
   | table definition author disabled title args updated eai:appName validation
   ```

1. Confirm the results contain the assets you want to migrate.

1. Above the results, click the export button, select the CSV format, and download the file.

1. Repeat for each resource type. Export the macros query if any of your alerts or dashboards use search macros.

The same instructions, with screenshots of the Splunk UI, are available in the import wizard under How to export your assets from Splunk?.

### Import your assets into Datadog{% #import-your-assets-into-datadog %}

1. Go to [Logs > Import](https://app.datadoghq.com/logs/batch-migration) and click Get Started.
1. In Select source, select Splunk Processing Language (SPL).
1. In Upload your assets from Splunk, add your alert and dashboard CSV files. Upload as many files as you need, but leave the macros file out of this step.
1. In Macros file, upload the macros CSV, if you have one.
1. In Name your import, give the import a name that identifies it later.
1. Click Import.

Translation starts as soon as the import is created and runs in the background. You can close the page and come back to it.

### Review and publish{% #review-and-publish %}

Open an import to see every resource it contains and the state of its translation:

| Status      | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| In Progress | The resource is being translated.                       |
| Translated  | A Datadog equivalent is ready to review and publish.    |
| Published   | The resource exists in Datadog. The import links to it. |
| Skipped     | The resource could not be translated.                   |

Click a resource to see its original SPL, the translated query, and the explanation of the translation. A translated query is not guaranteed to return the same results as the Splunk original. Review each translation before you publish the monitor or dashboard.

A dashboard shows a status for each of its widgets and publishes as a single dashboard. Open it to see which widgets were translated and which returned an error.

Monitors and dashboards with the Skipped status cannot be published, and a translation cannot be edited in Datadog before it is published. To correct a skipped resource, or a dashboard widget that returned an error, fix it at the source and import it again:

1. Correct the asset in Splunk and export it again, or edit the exported CSV directly. Editing the CSV is often faster for a small fix, such as renaming an index or attribute to match the one in Datadog.
1. (Optional) Delete the original import to reuse its name. On the [Import](https://app.datadoghq.com/logs/batch-migration) page, hover over the import, click the trash can icon, and then click Delete current migration.
1. Upload the corrected file as a new import.

## Translation gaps{% #translation-gaps %}

Translation converts SPL to Datadog log search syntax but does not guarantee identical results. These gaps account for most of the differences:

{% dl %}

{% dt %}
Logs have a different shape in each platform
{% /dt %}

{% dd %}
Pipelines, processors, and log-shipping agents differ between the two platforms. As a result, the attributes available on a log differ. The translator preserves attribute names as written, except when mapping [standard attributes](https://docs.datadoghq.com/standard-attributes.md). If a Datadog pipeline does not produce an attribute the Splunk query relies on, the translated query returns no results. To fix this, add [processors](https://docs.datadoghq.com/logs/log_configuration/processors.md) to your Datadog pipelines that produce the attribute. For example, use a Grok parser to extract it from the message, or a remapper to rename an existing attribute.
{% /dd %}

{% dt %}
Indexes do not match
{% /dt %}

{% dd %}
Splunk index names rarely map one-to-one to Datadog [log indexes](https://docs.datadoghq.com/logs/log_configuration/indexes.md). An index filter that does not resolve results in a query error. The translator strips index terms that have no Datadog equivalent and flags them as a warning. Review the warning and scope the query with tags or attributes instead.
{% /dd %}

{% dt %}
There is not enough sample data
{% /dt %}

{% dd %}
A query that runs against an index with little matching data returns an empty preview. An empty preview makes the translation hard to verify. Confirm that relevant logs are in Datadog before you assess a translation.
{% /dd %}

{% dt %}
The SPL command is not supported
{% /dt %}

{% dd %}
Query Translation supports a wide range of SPL commands. When a command does not have a Datadog equivalent, the translator returns as much of the query as it can and flags the unsupported command.
{% /dd %}

{% /dl %}

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Log search syntax](https://docs.datadoghq.com/logs/explorer/search_syntax.md)
- [DDSQL Editor](https://docs.datadoghq.com/ddsql_editor.md)
- [Log monitors](https://docs.datadoghq.com/monitors/types/log.md)
- [Dashboards](https://docs.datadoghq.com/dashboards.md)