Making a Change

Making a change in Causal is done like any other software change. You check out the branch on which you want to make the change and edit the FDL file.

When you run the Causal compiler on the FDL file, it will check that the change is compatible with your data warehouse. If so, it will generate a new type-safe API.

In order to understand any issues that come up during the data warehouse check, it's useful to understand how data is stored.

Feature Tables

Each feature defined in your FDL file will create a new table of the same name that represents that feature.

For example, say we have the following simple feature saved in a file test.fdl:

feature SimpleButton
{
    args {
        callToAction: String!
    }
    output {
        color: "blue"
    }
    event Click {}
}

We can generate the hive DDL code that will define the tables in data warehouse like so:

# generate ddl statements to load Causal data into a hive metastore
$ causalc --hive test.ddl test.fdl
[main] WARN io.causallabs.compiler.Compiler - No metadata available, not doing warehouse checks. You must specify --token and --environment
[main] WARN io.causallabs.compiler.Compiler - Unknown environment, not doing warehouse checks. You must specify --environment
$

The warnings are because we haven't specified our credentials or environment to the compiler, so it doesn't know which data warehouse to check against. Moving past that, inside the test.ddl file we see something like:

create table simple_button(
  sessionid string,
  impressionid string,
  firsttime timestamp,
  impressioncount bigint,
  callToAction string,
  color string,
  click array<struct<eventtime:timestamp>>
)
comment 'impression table for the Causal Simple_button feature'

Allowed Changes

You can see that each argument, output, and event type has it's own column, and those columns are strongly typed. Updated FDL will successfully compile as long data currently stored in the data warehouse can be converted to the new spec. In particular:

• you can add, delete, or reorder the arguments, outputs, or events
• you can add delete, or reorder the fields in a particular event
• you can change the type of existing data, as long as there is no data loss (ie, you can change an Int to a Float or an Int to a String)
• you can change an argument to be an output as well as vice versa as long as the types don't change

So in general, you are allowed to change a whole lot about a feature table over it's lifetime.

Checking the Front End

After your FDL change passes checks against the warehouse, check your front end code against the newly generated API. Fix any type errors, and add any newly required logging. Once you are happy that your code is working properly, you can commit the changes to your revision control system.