Skip to main content

Defining Your Data

The core part of the FDL file is the data definition. A feature definition follows this basic layout:

feature <name> {
    args {
        <argument fields>
    }
    output {
        <output fields>
    }
    event <name> {
        <event fields>
    } ...
}

Arguments​

Arguments are passed into Causal from the front end. You can specify the arguments for a feature using the args keyword. Each argument must have a unique name,1 and a GraphQL data type. If the data type is nullable (i.e., doesn't end in a !), it is treated as optional. You may request an impression of that feature without specifying that argument.

Each argument may optionally have a default value. In this case, you may also request an impression without specifying that argument, but the server will treat it as if you passed in the default.

Outputs​

Outputs are values that are passed back from Causal to your front end. You can specify them in the output section, which comes immediately after the feature's args section. They may be set using Causal's web UI, as part of a running experiment, or as the output of a machine learning model.

Each output also has a type. No matter what mechanism fills in the value, the front end code will not have to change. It can always expect a value of that type.

Default Values​

Outputs also have default values. However, they serve a very different purpose from argument default values.

The default values of your features describe the current state of your application. They are the base state that all your experiments and rollouts will modify. Experimentation with Causal proceeds as follows:

  1. Start with default values that represent the current state of the application
  2. Run experiments to try different values
  3. Make winning experiments the new defaults
  4. Repeat

Initially, the default values are specified in the FDL files using the name : type = default syntax. All outputs in an FDL file need this initial default because that is the value that the APIs will return before you commit your code and the Causal system learns about it.

For example let's say that you are adding a new output called button_text to a feature, with the default "CLICK ME". When you call your newly generated client code, it'll return "CLICK ME" for the button_text because you haven't committed your change and the Causal servers can't supply a different value. It's typical to use the defaults in the FDL file to test different values in your front end code before you commit your change for others to see.

One you commit your new FDL definition, people can start to experiment with different values for button_text without having to modify code. As new, better values are found they will become the new defaults, and the cycle will begin again.

Events​

Events are actions taken by your users, such as clicking a button or traversing a hyperlink. They represent explicit or implicit feedback your visitors give you on your product. Unlike other data handling systems, Causal's events can occur in some context, whether inside a feature or in the session definition. (as in the example above)

This means that a Causal event can be tied right back to the impression (and the impression content), on which it occurred. This is critical in helping to determine exactly how feature content and context (outputs and arguments) effect the performance of the feature on your site. It is also exactly what a data scientist needs to train a machine learning model to automatically optimize the content for a feature.

Offline Events​

Some events do not happen in your application. For example, you may have a visitor on your website that interacts with your application, then does something at a brick and mortar location or a partner website to convert. Since these events do not happen in your application, we call them offline events. Offline events can be signalled without a context and can be uploaded to your data warehouse using the typesafe Causal APIs. You can use these events to define experiment metrics that measure offline activity.

  1. All declared fields in the feature must have unique names because each field appears as a column in your data warehouse table. The compiler will give you an error if your fields have duplicate names.↩