Overview

DDSQL is SQL for Datadog data. It implements several standard SQL operations, such as SELECT, and allows queries against unstructured data. You can perform actions like getting exactly the data you want by writing your own SELECT statement, or querying tags as if they are standard table columns.

This documentation covers the SQL support available and includes:

• Syntax compatible with PostgreSQL
• Data types
• Type literals
• SQL functions
• Regular expressions
• Window functions
• JSON functions
• Table functions
• Tags

Syntax

The following SQL syntax is supported:

SELECT (DISTINCT) (DISTINCT: Optional)

Retrieves rows from a database, with DISTINCT filtering out duplicate records.

Copy

SELECT DISTINCT customer_id
FROM orders 

JOIN

Combines rows from two or more tables based on a related column between them. Supports FULL JOIN, INNER JOIN, LEFT JOIN, RIGHT JOIN.

Copy

SELECT orders.order_id, customers.customer_name
FROM orders
JOIN customers
ON orders.customer_id = customers.customer_id 

GROUP BY

Groups rows that have the same values in specified columns into summary rows.

Copy

SELECT product_id, SUM(quantity)
FROM sales
GROUP BY product_id 

|| (concat)

Concatenates two or more strings together.

Copy

SELECT first_name || ' ' || last_name AS full_name
FROM employees 

WHERE (Includes support for LIKE, IN, ON, OR filters)

Filters records that meet a specified condition.

Copy

SELECT *
FROM employees
WHERE department = 'Sales' AND name LIKE 'J%' 

CASE

Provides conditional logic to return different values based on specified conditions.

Copy

SELECT order_id,
  CASE
    WHEN quantity > 10 THEN 'Bulk Order'
    ELSE 'Standard Order'
  END AS order_type
FROM orders 

WINDOW

Performs a calculation across a set of table rows that are related to the current row.

Copy

SELECT
  timestamp,
  service_name,
  cpu_usage_percent,
  AVG(cpu_usage_percent) OVER (PARTITION BY service_name ORDER BY timestamp ROWS BETWEEN 2 PRECEDING AND CURRENT ROW) AS moving_avg_cpu
FROM
  cpu_usage_data 

IS NULL / IS NOT NULL

Checks if a value is null or not null.

Copy

SELECT *
FROM orders
WHERE delivery_date IS NULL 

LIMIT

Specifies the maximum number of records to return.

Copy

SELECT *
FROM customers
LIMIT 10 

ORDER BY

Sorts the result set of a query by one or more columns. Includes ASC, DESC for sorting order.

Copy

SELECT *
FROM sales
ORDER BY sale_date DESC 

HAVING

Filters records that meet a specified condition after grouping.

Copy

SELECT product_id, SUM(quantity)
FROM sales
GROUP BY product_id
HAVING SUM(quantity) > 10 

IN, ON, OR

Used for specified conditions in queries. Available in WHERE, JOIN clauses.

Copy

SELECT *
FROM orders
WHERE order_status IN ('Shipped', 'Pending') 

USING

This clause is a shorthand for joins where the join columns have the same name in both tables. It takes a comma-separated list of those columns and creates a separate equality condition for each matching pair. For example, joining T1 and T2 with USING (a, b) is equivalent to ON T1.a = T2.a AND T1.b = T2.b.

Copy

SELECT orders.order_id, customers.customer_name
FROM orders
JOIN customers
USING (customer_id) 

AS

Renames a column or table with an alias.

Copy

SELECT first_name AS name
FROM employees 

Arithmetic Operations

Performs basic calculations using operators like +, -, *, /.

Copy

SELECT price, tax, (price * tax) AS total_cost
FROM products 

INTERVAL value unit

Interval representing a time duration specified in a given unit. Supported units:
- milliseconds / millisecond
- seconds / second
- minutes / minute
- hours / hour
- days / day

Data types

DDSQL supports the following data types:

Array types

All data types support array types. Arrays can contain multiple values of the same data type.

Type literals

DDSQL supports explicit type literals using the syntax [TYPE] [value].

The type prefix can be omitted and the type is automatically inferred from the value. For example, 'hello world' is inferred as VARCHAR, 123 as BIGINT, and true as BOOLEAN. Use explicit type prefixes when values could be ambiguous; for example,TIMESTAMP '2025-01-01' would be inferred as VARCHAR without the prefix.

Array literals

Array literals use the syntax ARRAY[value1, value2, ...]. The array type is automatically inferred from the values.

SELECT ARRAY['apple', 'banana', 'cherry'] AS fruits; -- Inferred as VARCHAR array
SELECT ARRAY[1, 2, 3] AS numbers;                    -- Inferred as BIGINT array
SELECT ARRAY[true, false, true] AS flags;            -- Inferred as BOOLEAN array
SELECT ARRAY[1.1, 2.2, 3.3] AS decimals;             -- Inferred as DOUBLE array

Example

-- Using type literals in queries
SELECT
    VARCHAR 'Product Name: ' || name AS labeled_name,
    price * DOUBLE 1.08 AS price_with_tax,
    created_at + INTERVAL '7 days' AS expiry_date
FROM products
WHERE created_at > TIMESTAMP '2025-01-01';

Functions

The following SQL functions are supported. For Window function, see the separate Window function section in this documentation.

SELECT MIN(response_time) AS min_response_time
FROM logs
WHERE status_code = 200

SELECT MAX(response_time) AS max_response_time
FROM logs
WHERE status_code = 200

SELECT COUNT(request_id) AS total_requests
FROM logs
WHERE status_code = 200 

SELECT SUM(bytes_transferred) AS total_bytes
FROM logs
GROUP BY service_name

SELECT AVG(response_time)
AS avg_response_time
FROM logs
WHERE status_code = 200
GROUP BY service_name

SELECT BOOL_AND(status_code = 200) AS all_success
FROM logs

SELECT BOOL_OR(status_code = 200) AS some_success
FROM logs

SELECT CEIL(price) AS rounded_price
FROM products

SELECT FLOOR(price) AS floored_price
FROM products

SELECT ROUND(price) AS rounded_price
FROM products

SELECT LOWER(customer_name) AS lowercase_name
FROM customers

SELECT UPPER(customer_name) AS uppercase_name
FROM customers

SELECT ABS(balance) AS absolute_balance
FROM accounts

SELECT COALESCE(phone_number, email) AS contact_info
FROM users

SELECT
  CAST(order_id AS VARCHAR) AS order_id_string,
  'Order-' || CAST(order_id AS VARCHAR) AS order_label
FROM
  orders

SELECT
  customer_name,
  LENGTH(customer_name) AS name_length
FROM
  customers

SELECT
  TIMESTAMP '2023-10-01 10:00:00' + INTERVAL '30 days' AS future_date,
  INTERVAL '1 MILLISECOND 2 SECONDS 3 MINUTES 4 HOURS 5 DAYS'

SELECT
  TRIM(name) AS trimmed_name
FROM
  users

SELECT
  REPLACE(description, 'old', 'new') AS updated_description
FROM
  products

SELECT
  SUBSTRING(title, 1, 10) AS short_title
FROM
  books

SELECT
  STRPOS('foobar', 'bar')

SELECT
  SPLIT_PART('aaa-bbb-ccc', '-', 2)

SELECT
  EXTRACT(year FROM purchase_date) AS purchase_year
FROM
  sales

SELECT
  TO_TIMESTAMP('25/12/2025 04:23 pm', 'DD/MM/YYYY HH:MI am') AS ts

SELECT
  TO_CHAR(order_date, 'MM-DD-YYYY') AS formatted_date
FROM
  orders

SELECT DATE_BIN('15 minutes', TIMESTAMP '2025-09-15 12:34:56', TIMESTAMP '2025-01-01')
-- Returns 2025-09-15 12:30:00

SELECT DATE_BIN('1 day', TIMESTAMP '2025-09-15 12:34:56', TIMESTAMP '2025-01-01')
-- Returns 2025-09-15 00:00:00

SELECT
  DATE_TRUNC('month', event_time) AS month_start
FROM
  events

-- Define the current analysis window
WITH bounds AS (
  SELECT CAST(CURRENT_SETTING('dd.time_frame_start') AS TIMESTAMP) AS time_frame_start,
         CAST(CURRENT_SETTING('dd.time_frame_end')   AS TIMESTAMP) AS time_frame_end
),
-- Define the immediately preceding window of equal length
     previous_bounds AS (
  SELECT time_frame_start - (time_frame_end - time_frame_start) AS prev_time_frame_start,
         time_frame_start                                       AS prev_time_frame_end
  FROM bounds
)
SELECT * FROM bounds, previous_bounds

SELECT
  *
FROM
  sales
WHERE
  purchase_date > NOW() - INTERVAL '1 hour'

SELECT
  CARDINALITY(recipients)
FROM
  emails

SELECT
  ARRAY_POSITION(recipients, 'hello@example.com')
FROM
  emails

SELECT
  STRING_TO_ARRAY('a,b,c,d,e,f', ',')

SELECT
  sender,
  ARRAY_AGG(subject) subjects,
  ARRAY_AGG(ALL subject) all_subjects,
  ARRAY_AGG(DISTINCT subject) distinct_subjects
FROM
  emails
GROUP BY
  sender

SELECT
  sender,
  recipient
FROM
  emails,
  UNNEST(recipients) AS recipient

Regular expressions

Flavor

All regular expression (regex) functions use the International Components for Unicode (ICU) flavor:

• Metacharacters
• Operators
• Set Expressions (Character Classes)
• Flag Options for in-pattern flags. Refer to the flags section below for function-level flags.
• Find and Replace (using capture groups)

Functions

SELECT
  *
FROM
  emails
WHERE
  REGEXP_LIKE(email_address, '@example\.com$')

SELECT regexp_match('foobarbequebaz', '(bar)(beque)');
-- {bar,beque}

SELECT regexp_match('foobarbequebaz', 'barbeque');
-- {barbeque}

SELECT regexp_match('abc123xyz', '([a-z]+)(\d+)(x(.)z)');
-- {abc,123,xyz,y}

SELECT regexp_replace('Auth success token=abc123XYZ789', 'token=\w+', 'token=***');
-- Auth success token=***

SELECT regexp_replace('status=200 method=GET', 'status=(\d+) method=(\w+)', '$2: $1');
-- GET: 200

SELECT regexp_replace('INFO INFO INFO', 'INFO', 'DEBUG', 1, 2);
-- INFO DEBUG INFO

Function-level flags

You can use the following flags with regular expression functions:

i

Case-insensitive matching

n or m

Newline-sensitive matching

g

Global; replace all matching substrings rather than only the first one

SELECT regexp_match('INFO', 'info')
-- NULL

SELECT regexp_match('INFO', 'info', 'i')
-- ['INFO']

SELECT regexp_match('a
b', '^b');
-- NULL

SELECT regexp_match('a
b', '^b', 'n');
-- ['b']

SELECT icu_regexp_replace('Request id=12345 completed, id=67890 pending', 'id=\d+', 'id=XXX');
-- Request id=XXX completed, id=67890 pending

SELECT regexp_replace('Request id=12345 completed, id=67890 pending', 'id=\d+', 'id=XXX', 'g');
-- Request id=XXX completed, id=XXX pending

Window functions

This table provides an overview of the supported window functions. For comprehensive details and examples, see the PostgreSQL documentation.

JSON functions and operators

Table functions

Table functions are used to query Logs and Metrics

dd.logs(
    filter => varchar,
    columns => array < varchar >,
    indexes ? => array < varchar >,
    from_timestamp ? => timestamp,
    to_timestamp ? => timestamp
) AS (column_name type [, ...])

SELECT timestamp, host, service, message
FROM dd.logs(
    filter  => 'source:java',
    columns => ARRAY['timestamp','host', 'service','message']
) AS (
    timestamp TIMESTAMP,
    host      VARCHAR,
    service   VARCHAR,
    message   VARCHAR
)

dd.metric_scalar(
    query varchar,
    reducer varchar [, from_timestamp timestamp, to_timestamp timestamp]
)

SELECT *
FROM dd.metric_scalar(
    'avg:system.cpu.user{*} by {service}',
    'avg',
    TIMESTAMP '2025-07-10 00:00:00.000-04:00',
    TIMESTAMP '2025-07-17 00:00:00.000-04:00'
)
ORDER BY value DESC;

Tags

DDSQL exposes tags as an hstore type, which is inspired by PostgreSQL. You can access the values for specific tag keys using the PostgreSQL arrow operator. For example:

SELECT instance_type, count(instance_type)
FROM aws.ec2_instance
WHERE tags->'region' = 'us-east-1' -- region is a tag, not a column
GROUP BY instance_type

Tags are key-value pairs where each key can have zero, one, or multiple tag values corresponding to it. When accessed, the tag value returns a single string, containing all corresponding values. When the data has multiple tag values for the same tag key, they are represented as a sorted, comma-separated string. For example:

SELECT tags->'team', instance_type, architecture, COUNT(*) as instance_count
FROM aws.ec2_instance
WHERE tags->'team' = 'compute_provisioning,database_ops'
GROUP BY tags->'team', instance_type, architecture
ORDER BY instance_count DESC

You can also compare tag values as strings or entire tag sets:

SELECT *
FROM k8s.daemonsets da INNER JOIN k8s.deployments de
ON da.tags = de.tags -- for a specific tag: da.tags->'app' = de.tags->'app'

Further reading

Additional helpful documentation, links, and articles:

Learn more about DDSQL EditorDOCUMENTATION