Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modify the cut/coalesce example in Zed language docs #4776

Merged
merged 2 commits into from
Sep 22, 2023
Merged

Conversation

philrz
Copy link
Contributor

@philrz philrz commented Sep 21, 2023

These are additional changes beyond the ones first merged in #4773 (thanks @iloveitaly!).

Traditionally, the docs have taken an approach of trying to show language components mostly in isolation using small examples. The hope is that the user will see them as building blocks such that they'll combine them with other components in useful ways. To the degree that there's specific combinations that enable powerful use cases, we've tried to reveal these through the tutorials, CLI command walk-throughs, and so forth.

Meanwhile, the docs improvements in #4773 were from a community user that had started from a use case that:

  1. Depended on a specific component (the cut operator)
  2. Combined that with an operation (output as CSV)
  3. Hit a common problem (the CSV writer's reliance on data already being of a single record type)
  4. Found a particular solution to the problem (using the coalesce() function to create that single record type.)

It turns out there's other ways to address the limitation (e.g., using the fuse operator, or specifying the null value as int64 type in the input data) and there's other other use cases that would benefit from this same treatment (e.g., outputting heterogenous records without cut, or output in Parquet format). Therefore the original text might benefit from some tweaks.

Here I've tried to make the example a little more widely applicable by noting:

  1. This happens to be showing another example of how to invoke functions in the RHS of a field expression (thanks for that suggestion @mattnibs!)
  2. It's as applicable to Parquet output as CSV
  3. As the CSV writer's error messages also inform the user, fuse is yet another available approach

I also used some of the Docusaurus formatting to present the use case context differently.

image

@philrz philrz requested a review from a team September 21, 2023 23:27
@philrz philrz self-assigned this Sep 21, 2023
Copy link
Collaborator

@mattnibs mattnibs left a comment

Choose a reason for hiding this comment

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

Lovely!

@philrz philrz merged commit 8f4bc8d into main Sep 22, 2023
4 checks passed
@philrz philrz deleted the cut-coalesce-example branch September 22, 2023 18:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants