Naming Apocalypse

[mtoy-googly-moogly]

Comprehension Debt

While we were figuring out the nouns and verbs of a malloy like approach to data, we used a lot of words that already have meanings, and before we ship to the world, I think we should tighten things up to clarify for ourselves when we are reading code, and for people just wandering into Malloy and wanting to use.

I have a personal vendetta against the "model" and "query". They mean too many things. In the end, if we use the word "query" anywhere, it should only mean the thing we are building to execute on the database engine.

This will involve re-naming things internally as well as fixing the external API.

Here are some thoughts on this, scribbled down so I can get back to the thing I am supposed to be working on. Some of this assumes that the distinction between a "source" and a "query" in the current language will be going away.

This is meant to spark discussion, there are some choices here that I disagreed with the moment I wrote them.

Model -> Frame

The thing you get when you compile a malloy file

Frame

alternatives ... Document, Registry, Catalog, Compendium, Canon, Index

Model Contents -> Entry

The thing you get when you look at named objects in the CMF (Compiled Malloy File)

Entry

alternatives .... Entity,Article,Thing,Item,Object

In use, it would go something like this ...

    fooFrame = runtime.loadFrame(fileURL);
    foo = fooFrame.loadEntry("foo");
    // StructDef, Query and SQL block entries will both respond to these
    fooResult = foo.run();
    fooFields = foo.fields();
    fooSQL = foo.sql();

If there are things like abstract sources ... you could do some sort of discriminators

    foo.isAbstract();
    foo.isConcrete();
    foo.isRunnable();

    flexFoo = fooFrame.loadEntry("flex");
    // flexFoo.isRunnable() == false
    if (flexFoo.isAbstract()) {
        unflex = flexFoo.resolve({ param1: value1, param2: value2 });
        // unflex.isRunnable() = true
        unflex.run();
    }

To run some code on an existing frame ....

    [ extendedFrame, extendFoo ] = fooFrame.extendModel('new code');
    thisResult = extendedFoo.run();

Query -> Pipeline

This is a pipeline with a source at the head and zero or more steps.

alternatives ... Process,Inquiry

QuerySegment -> Stage

alternatives -- Segment, Step, Phase

This is a "project", a "reduce", or an "index"

QueryQuery -> NamedPipe

This is a field in a source or a queryl which is a pipeline,
since it always has a name, this one is kind of easy

QueryField (and family) -> StageField

[mtoy-googly-moogly]

In chat @bporterfield wrote

I guess I have few opinions about code naming, but if this impacts APIs and error messages - so users see it - my take is "name it the thing people will call it anyways". Meaning, if someone is gonna say "we call a query in Malloy a fiddleflop" every time they teach Malloy, i think we should probably just call that thing a query. I think it reduces blockers to grocking what we do. I'm not convinced Looker had trouble because "model" and "query" are overloaded, I actually think the opposite, that using those names made it obvious to folks what things were without needing additional explanation

I think that is important too.

[mtoy-googly-moogly]

This sent me a-thinking and I have this new twist on the idea. What if in Malloy query is a verb, it is a method you call on malloy objects, but none of them ARE a query, but all of them can be queried.