Skip to content

fix grammar and clarity in features and tao #75

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions src/documentation/about/features.malloynb
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Data Model. Malloy queries (equivalent of SQL's <code>SELECT</code>) run agains
produce SQL.

### Filtering Data
The first step in working with data, often is isolating the data you are interested in.
The first step in working with data is often isolating the data you are interested in.
Malloy introduces [simplified filtering](../language/filters.malloynb) for all types and allows these filters to be
applied. [Time calculations](../language/expressions.malloynb#time-expressions) are powerful and understandable.

Expand All @@ -23,11 +23,10 @@ mapping values, bucketing results and data cleanup.

### Maintains Relationships
SQL's <code>SELECT</code> statement flattens the namespace into a wide table. Malloy retains the graph relationship
of data lets you access and correctly perform computations and any place in the graph.
of data which lets you access and correctly perform computations and any place in the graph.

### Reusable Queries
Queries can be introduced into a Malloy model and accessed by name. One benefit is that the
queries are always accurate. Think of a Malloy model as a data function library.
Copy link
Author

@vitiral vitiral Aug 11, 2023

Choose a reason for hiding this comment

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

I'm not sure what One benefit is that the queries are always accurate means but it is neither clear nor can it possibly be accurate 😄

I wish I could have a programming language who's queries are always accurate but then most Data Scientists would probably be out of a job!

Queries can be introduced into a Malloy model and accessed by name. Think of a Malloy model as a data function library.
Queries can also be used to create [nested subtables](../language/nesting.malloynb) in other queries.

### Aggregating Subqueries
Expand All @@ -38,6 +37,6 @@ Named queries of a given shape can easily be nested, visualized and reused.
Malloy can pipeline operations. The output of one query can be the input for next.

### Metadata, Visualization and Drilling
Compiling a Malloy query returns metadata about the structure of the results. When combined with the query results, Malloy's rendering library can give a very
rich user experience, rendering dashboards, visualizations. Through this metadata
the visualization library can rewrite queries to drill through to data detail.
Compiling a Malloy query returns metadata about the structure of the results. When combined with the query results, Malloy's rendering library
automatically renders very rich dashboards and visualations so that you can iteratively
explore and drill down into the data details.
14 changes: 7 additions & 7 deletions src/documentation/about/tao.malloynb
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,16 @@ Our primary users will all be familiar with SQL. We should make their life no ha
For example `name is expression`, vs `expression as name`. In SQL the naming on an expression sits as a casual afterthought "oh by the way, give this really important expression a name". In Malloy, the name of a thing is important, you are building complex things from smaller pieces. When you look at a model, you will often want to scan the file looking for names, they belong on the left hand side.


However, we in general try to have the "feel" of SQL. We use `()` for structuring instead of `{}` like LookML or JavaScript do, or indentation like Python does. We use `is` and `define` instead of `:` like LookML or `=` like JavaScript. We use SQL words for things (like `join`) where it makes sense.
However try to keep to the "feel" of SQL while incorporating useful syntax from other languages. We use `()` for structuring instead of `{}` (LookML/JavaScript), or whitespace/indentation (Python). When a concept or function is particular to query languages we try to fall back to use SQL words (i.e. `join`, `aggregate`) but do not introduce whitespace syntax (i.e. Malloy's `group_by` vs SQL's `GROUP BY`)


The intention was always that there is some context, command line or editor, which handles a single document with mixed Malloy and SQL, either because they are one merged language, or there is some JSX-like escaping between the contexts.
The intention has always been to allow mixing Malloy and SQL in order to enable incremental improvement of already existing SQL; as well as better facilitate the learning process.
Copy link
Author

Choose a reason for hiding this comment

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

I felt like the reference to JSX/etc was superfluous. The main point (as I see it) is that you should be able to incrementally improve your SQL code.


### … feels concise, but not cryptic
This is the most common point of disagreement as we talk about how to express things. There is no one right answer to this. We have a preference for brevity, every single feature we wrestle with trying to get the most clarity from the least language surface.
This is the most common point of disagreement as we talk about how to express things. There is no one right answer to this. We have a preference for brevity but require clarity. Every single feature we wrestle with trying to get the most readability from the least language surface.

### … is composable
If you find a piece of code that works, you should be able to select it, paste it somewhere with a name, and use it by name.
If you find a piece of code that works, you should be able to (at best) import it or (at worst) copy/paste it somewhere and use it by name.

### … is an algebra for computations with relational data
Malloy comprehends data as a network of relationships and so computations like aggregation have a useful and mathematical meaning. Malloy gestures should read like a mathematical formula which means one clear thing.
Expand All @@ -29,13 +29,13 @@ Malloy comprehends data as a network of relationships and so computations like a
Maybe AppleScript or COBOL would be at the extreme end of this. More of a kind of math, less like a natural language.

### … is curated
There are not four different ways to express things depending on which programming language or style you came from. There is one, and it is carefully chosen to match the task of data transformation, discovery and presentation.
There are not four equal and different ways to express something. In Malloy there should be one preferred way that has been carefully chosen to match the task of data transformation, discovery and presentation.

### … is helpful
Malloy tries to "do the right thing" that most people want, by default, while still allowing non default expressions to be written. The treatment of `null` and booleans, and the sorting rules for "reduce" stages would be two examples of this.
Malloy tries to "do the right thing" that most people want, by default, while still allowing non default expressions to be written. The treatment of `null` and booleans, and the sorting rules for "reduce" stages are two examples of this.

### … is still an experiment
We had some theoretical insights that there was a better way to interact with data than SQL, and Malloy is the current snapshot of that thinking, but we are not done. We have a number of features which are not yet in the language, which we expect to have an impact on the language, and maybe even on these rules. The language is still young and needs room to grow.

### … is an expression of empathy towards explorers and explainers of data
The Malloy user is not someone who writes one sentence in Malloy, and then never sees the language again. Malloy is an invitation into a "way" for people who are passionate about decision making based on data, and good decision making is iterative, and ongoing.
The Malloy user is not someone who writes one sentence in Malloy, and then never sees the language again. Malloy is an invitation into a "way" (or "Tao") for people who are passionate about decision making based on data; and good decision making is iterative and ongoing.
Copy link
Author

@vitiral vitiral Aug 11, 2023

Choose a reason for hiding this comment

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

"The Tao" literally translated can mean "The way" so there is a pun here that feels like a good way to end a document titled "Tao"

https://en.wikipedia.org/wiki/Tao

[Tao] means a road, path, way;