[DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages #127215

leemthompo · 2025-04-23T08:28:14Z

Contributes to #126897

URL Previews

Summary

Main goal is to ensure both pages have clear distinctions and cross-reference each other.

lookup-join.md (syntax reference):

add link to high-level landing page
improved parameter formatting and descriptions
fixed template variable from {esql} to {{esql}}

esql-lookup-join.md (landing page):

9d23f24 adds improved example with setup code

improve layout:

added "compare with enrich" section header
simplified "how the command works" with clearer parameter explanation
added code example in how it works section
improved image alt text for accessibility
organized example section with better context and SQL comparison
added dropdown for sample tables to reduce visual clutter
added "query" subheading for clearer organization
included reference to additional examples in command reference

…nding pages **lookup-join.md (syntax reference)**: - removed tip formatting for simpler direct link to landing page - improved parameter formatting and descriptions - fixed template variable from `{esql}` to `{{esql}}` **esql-lookup-join.md (landing page)**: - added "compare with enrich" section header - simplified "how the command works" with clearer parameter explanation - added code example in how it works section - improved image alt text for accessibility - organized example section with better context and SQL comparison - added dropdown for sample tables to reduce visual clutter - added "query" subheading for clearer organization - included reference to additional examples in command reference - removed excessive whitespace

elasticsearchmachine · 2025-04-23T08:29:32Z

Pinging @elastic/es-docs (Team:Docs)

alex-spies

Thanks Liam! I have some minor remarks and suggestions, but otherwise this LGTM and it's a nice improvement over the previous version.

Please feel free to address the remarks at your own discretion.

Also, we probably want to manually backport (an adapted version of) this to the 8.18/8.x docs, right?

alex-spies · 2025-04-23T08:58:00Z

docs/reference/query-languages/esql/esql-lookup-join.md


-`<field_name>`
-: The field to join on. This field must exist in both your current query results and in the lookup index. If the field contains multi-valued entries, those entries will not match anything (the added fields will contain `null` for those rows).
+If you're familiar with SQL, `LOOKUP JOIN` has left-join behavior. This means that if no rows match in the lookup index, the incoming row is retained and `null`s are added. If many rows in the lookup index match, `LOOKUP JOIN` adds one row per match.


Should this paragraph be in the example section? It looks like it would fit better just above it.

alex-spies · 2025-04-23T09:01:02Z

docs/reference/query-languages/esql/esql-lookup-join.md


-`LOOKUP JOIN` has left-join behavior. If no rows match in the lookup index, `LOOKUP JOIN` retains the incoming row and adds `null`s. If many rows in the lookup index match, `LOOKUP JOIN` adds one row per match.
+In this example, we have two sample tables, `employees` and `languages_non_unique_key`. The `employees` table contains employee information, including their language code. The `languages_non_unique_key` table contains language codes and their corresponding names and countries.


out of scope: languages_non_unique_key is a weird name for an index IMO; it makes sense in the context of the tests that this is taken from, but doesn't mean much to readers of this page, I think.

This extends to the example query below, which doesn't provide a meaningful example from real life. It'd be nicer to have an example that is intuitive for new users of this command.

The same applies to some of the examples in the reference entry (in lookup-join.md) that were taken directly from our test. The threat hunting examples are much better, in contrast.

I agree, I think we should just make the example on the landing page be super simple. I can do that in this PR. Then we can think about how to improve the examples in the reference entry in a follow up and/or think about more end-to-end tutorials.

I didn't want to blow the scope of this PR, but if you'd like to add a better example right away, that's great! I'm happy either way :)

I think we can work with what we have just make it a little clearer and user-friendly :)

for folks following along decided to improve the example completely: 9d23f24

alex-spies · 2025-04-23T09:01:52Z

docs/reference/query-languages/esql/esql-lookup-join.md


-In this example, we have two sample tables:
+:::{dropdown} Show the sample tables


The dropdown is great and looks much cleaner!

docs/reference/query-languages/esql/esql-lookup-join.md

alex-spies · 2025-04-23T09:12:55Z

docs/reference/query-languages/esql/esql-lookup-join.md

 ::::

+### Additional examples
+
+Refer to the examples section of the [`LOOKUP JOIN`](/reference/query-languages/esql/commands/processing-commands.md#esql-lookup-join) command reference for more examples.


replaced abstract employee/language example with security monitoring use case added setup instructions for creating test indices included sample data loading via bulk api new practical query example joining firewall logs with threat data simplified results output showing threat detection scenario added note about left-join behavior improved code comments and structure added required index.mode: lookup setting info

alex-spies · 2025-04-23T11:15:59Z

docs/reference/query-languages/esql/esql-lookup-join.md

Much nicer example, thank you!

elasticsearchmachine · 2025-04-23T11:23:57Z

💚 Backport successful

Status	Branch	Result
✅	9.0

…nding pages (elastic#127215) * [DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages **lookup-join.md (syntax reference)**: - removed tip formatting for simpler direct link to landing page - improved parameter formatting and descriptions - fixed template variable from `{esql}` to `{{esql}}` **esql-lookup-join.md (landing page)**: - added "compare with enrich" section header - simplified "how the command works" with clearer parameter explanation - added code example in how it works section - improved image alt text for accessibility - organized example section with better context and SQL comparison - added dropdown for sample tables to reduce visual clutter - added "query" subheading for clearer organization - included reference to additional examples in command reference - removed excessive whitespace * Improve example, add setup code replaced abstract employee/language example with security monitoring use case added setup instructions for creating test indices included sample data loading via bulk api new practical query example joining firewall logs with threat data simplified results output showing threat detection scenario added note about left-join behavior improved code comments and structure added required index.mode: lookup setting info

…nding pages (#127215) (#127232) * [DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages **lookup-join.md (syntax reference)**: - removed tip formatting for simpler direct link to landing page - improved parameter formatting and descriptions - fixed template variable from `{esql}` to `{{esql}}` **esql-lookup-join.md (landing page)**: - added "compare with enrich" section header - simplified "how the command works" with clearer parameter explanation - added code example in how it works section - improved image alt text for accessibility - organized example section with better context and SQL comparison - added dropdown for sample tables to reduce visual clutter - added "query" subheading for clearer organization - included reference to additional examples in command reference - removed excessive whitespace * Improve example, add setup code replaced abstract employee/language example with security monitoring use case added setup instructions for creating test indices included sample data loading via bulk api new practical query example joining firewall logs with threat data simplified results output showing threat detection scenario added note about left-join behavior improved code comments and structure added required index.mode: lookup setting info

- I trimmed the KEEP query in my final iteration in elastic#127215 but neglected to update the query itself, only the response. This fixes that so the query matches the response. - 🚘 I also updated the table response to match other ESQL response tables

- I trimmed the KEEP query in my final iteration in #127215 but neglected to update the query itself, only the response. This fixes that so the query matches the response. - 🚘 I also updated the table response to match other ESQL response tables

- I trimmed the KEEP query in my final iteration in elastic#127215 but neglected to update the query itself, only the response. This fixes that so the query matches the response. - 🚘 I also updated the table response to match other ESQL response tables

- I trimmed the KEEP query in my final iteration in #127215 but neglected to update the query itself, only the response. This fixes that so the query matches the response. - 🚘 I also updated the table response to match other ESQL response tables

leemthompo self-assigned this Apr 23, 2025

elasticsearchmachine added needs:triage Requires assignment of a team area label v9.1.0 labels Apr 23, 2025

leemthompo added >docs General docs changes Team:Docs Meta label for docs team auto-backport Automatically create backport pull requests when merged v9.0.0 and removed needs:triage Requires assignment of a team area label labels Apr 23, 2025

leemthompo requested a review from alex-spies April 23, 2025 08:32

alex-spies approved these changes Apr 23, 2025

View reviewed changes

alex-spies reviewed Apr 23, 2025

View reviewed changes

docs/reference/query-languages/esql/esql-lookup-join.md

Copy link

Contributor

alex-spies Apr 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Much nicer example, thank you!

leemthompo reacted with heart emoji

alex-spies approved these changes Apr 23, 2025

View reviewed changes

leemthompo merged commit 2c2e9a5 into elastic:main Apr 23, 2025
6 checks passed

leemthompo mentioned this pull request Apr 23, 2025

[9.0] [DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages (#127215) #127232

Merged

leemthompo added the :Analytics/ES|QL AKA ESQL label Apr 23, 2025

leemthompo deleted the esql-dedupe-lookup-join branch April 23, 2025 14:52

leemthompo mentioned this pull request Apr 24, 2025

[DOCS] Update esql-lookup-join.md #127306

Merged

This was referenced Apr 24, 2025

[DOCS][ESQL][8.x] Cleanup and cross-reference LOOKUP JOIN reference and landing pages #127316

Merged

[Issue]: Apr 15th v9.0 LOOKUP JOIN documentation example makes no sense elastic/docs-content#1155

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages #127215

[DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages #127215

leemthompo commented Apr 23, 2025 •

edited

Loading

elasticsearchmachine commented Apr 23, 2025

alex-spies left a comment

alex-spies Apr 23, 2025

leemthompo Apr 23, 2025

alex-spies Apr 23, 2025

leemthompo Apr 23, 2025

alex-spies Apr 23, 2025

leemthompo Apr 23, 2025

leemthompo Apr 23, 2025 •

edited

Loading

alex-spies Apr 23, 2025

alex-spies Apr 23, 2025

alex-spies Apr 23, 2025

elasticsearchmachine commented Apr 23, 2025


		`LOOKUP JOIN` has left-join behavior. If no rows match in the lookup index, `LOOKUP JOIN` retains the incoming row and adds `null`s. If many rows in the lookup index match, `LOOKUP JOIN` adds one row per match.
		In this example, we have two sample tables, `employees` and `languages_non_unique_key`. The `employees` table contains employee information, including their language code. The `languages_non_unique_key` table contains language codes and their corresponding names and countries.


		In this example, we have two sample tables:
		:::{dropdown} Show the sample tables

[DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages #127215

[DOCS][ESQL] Cleanup and cross-reference LOOKUP JOIN reference and landing pages #127215

Conversation

leemthompo commented Apr 23, 2025 • edited Loading

URL Previews

Summary

elasticsearchmachine commented Apr 23, 2025

alex-spies left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leemthompo Apr 23, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elasticsearchmachine commented Apr 23, 2025

💚 Backport successful

leemthompo commented Apr 23, 2025 •

edited

Loading

leemthompo Apr 23, 2025 •

edited

Loading