Consolidate DDSQL references

[estherk15]

What does this PR do? What is the motivation?

This PR consolidates the DDSQL references for Workspaces and the DDSQL Editor into a single resource page.

DOCS-10588

🧩 Problem this solves:

• There are currently two DDSQL references for two Preview products, each with different levels of syntax support. This has led to confusion, as customers often mix up which syntax applies to which product.
• While this currently affects only a few hundred customers, Workspaces is expected to GA by the end of the month, and the confusion will scale.
• Creating a single entry point for DDSQL information should reduce misinterpretation and help customers get to the right syntax faster.
• This also aligns with future plans to maintain a single, unified DDSQL reference.

What to look for during review:

• If you were a new user, would it be clear which syntax applies to your product?
• Do all links and aliases point to the correct DDSQL documentation?
• The content itself hasn't changed, but an alert box was added to clarify that there are two versions of DDSQL, and to guide users to the correct one based on their product.

Merge instructions

Merge readiness:

• Ready for merge

For Datadog employees:
Merge queue is enabled in this repo. Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). Without this format, your pull request will not pass in CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.

If your branch doesn't follow this format, rename it or create a new branch and PR.

To have your PR automatically merged after it receives the required reviews, add the following PR comment:

/merge

Additional notes

[github-actions]

Preview links (active after the build_preview check completes)

New or renamed files

• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_reference/
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_reference/ddsql_editor_syntax

Renamed files

• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_editor/tags
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_reference/ddsql_default
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_reference/ddsql_editor_syntax/data_types
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_reference/ddsql_editor_syntax/expressions_and_operators
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_reference/ddsql_editor_syntax/functions
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_reference/ddsql_editor_syntax/statements
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_reference/ddsql_editor_syntax/window_functions

Modified Files

• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_editor/
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_editor/getting_started
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/ddsql_editor/reference_tables
• https://docs-staging.datadoghq.com/esther/docs-10588-ddsql-reference/logs/workspaces/

[janine-c]

Hey Esther! This looks like a gigantic chonk of work; nice job!

I left some minor comments; let me know if you have any questions 🙂 Overall, I think this is a bit of a tough nut to crack if you aren't already familiar with what's happening (what am I saying, I'm clearly talking about myself 😂). The current docs make it sound like the SQL reference is just generic SQL, which makes the new labelling of DDSQL a bit confusing - is it the same SQL someone might learn at another company, or is it now something unique to us? I don't know enough about it to make a call!

I also struggled to understand why the DDSQL Editor content was split between the DDSQL and DDSQL Editor sections in the left nav - I don't understand enough about why they're different, and struggled to intuit why some content would be in one section or the other. I wonder if if renaming DDSQL to DDSQL Reference might help clear that up? Again, I'm not entirely sure what's right based on the problem we're solving here.

Lastly, while I don't think there's anything with the disclaimers you added in this PR, I think the framing is different from what you described in the PR description, so I thought I'd bring it up. The disclaimers frame this distinction as a matter of support, and kind of gloss over the fact that there are two versions of DDSQL - it kind of maybe sounds like the differences are quite minor. Your description here frames it around two versions of DDSQL, which isn't really mentioned in the disclaimers, which also makes the differences sound more significant and important to understand! I think I prefer the explicit "hey, there are two different versions with different support" angle, rather than the "the DDSQL Editor might not support some syntax" angle, if that makes sense?

Again, let me know if you'd like to chat about this more. It seems like a lot to understand, and that can be tough to express in the docs. But you've done a great job so far!

[jinatdatadog]

Could we make "DDSQL Editor Syntax (Preview)" --> "DDSQL v0 (for DDSQL Editor Preview)"
And "DDSQL for the DDSQL Editor" --> "DDSQL v0"?

Can we also remove this banner in the "DDSQL for the DDSQL Editor" tab? Its redundant, since the banner is already in the "DDSQL" tab

Thanks for this!

[TylerMills]

For the tabs, what do we think about:

• v1
• v0 (Preview)

I do think that putting 'DDSQL Editor' in tabs might cause more confusion though since DDSQL Editor will have v1 eventually. @jinatdatadog

[estherk15]

For the tabs, what do we think about:

• v1
• v0 (Preview)

I do think that putting 'DDSQL Editor' in tabs might cause more confusion though since DDSQL Editor will have v1 eventually. @jinatdatadog

@TylerMills @jinatdatadog @janine-c
Thanks for the feedback! I see the reasoning behind using V0/V1 to differentiate the two DDSQL syntaxes and trying to reduce confusion when DDSQL supports eventually "V1" syntax. I opted for DDSQL and DDSQL Editor Syntax (Preview) because version labels feel like implementation details the docs should abstract away, especially since the syntaxes aren’t strictly linear or backward-compatible. Product-specific labels reflect the current user experience and help users self-identify the right reference.

As DDSQL Editor begins to adopt the broader syntax, we can revisit the framing to ensure the docs stay intuitive and accurate for customers!

[TylerMills]

@estherk15 "As DDSQL Editor begins to adopt the broader syntax, we can revisit the framing to ensure the docs stay intuitive and accurate for customers!"

I think the plan is to start exposing this in the next week or so (but will run in parallel with old version) so I think these tabs are still confusing.

[estherk15]

@TylerMills Thanks for the additional context. How long do you plan to run these in parallel and which features are you enabling for customers? Or is it just that customers can either use the DDSQL Editor syntax vs. Workspaces syntax? How are you communicating this to DDSQL Editor users?

[jinatdatadog]

@estherk15 we'll have the appropriate in-app enablement/documentation for DDSQL Editor customers. The plan is to allow them to use both syntax in DDSQL Editor from DASH for ~2 months. After that we'll do a hard cutover where all DDSQL Editor customers are using DDSQL (and not DDSQL Editor Preview Syntax)

I can reach out when we do that hard cutover to have the DDSQL Editor Preview Syntax deprecated

[urseberry]

How does the user know which syntax they are using in the app? Do V0 and V1 appear in the app?