Keywords

The syntax descriptions on this page use angle brackets (< >) to call out various entities in the syntax, which will be defined after the example unless it is obvious what they mean.

Ellipses (...) mean that particular pattern can be repeated several times.

Brackets ([ ]) denote optional sections.

@ Directives

Directives are annotations on an entity in FDL that modifies it's behavior in some way. They are similar to GraphQL directives. Depending on the directive, it can be placed after the name of a new feature or event that you are writing, or after a field definition. For example:

feature example
@no_gate ## don't allow feature gating on this feature
{
    obsolete: Int! @deprecated( reason: "This is old, you can remove it from the code")
}

@deprecated

@deprecated[ (reason: <reason> ) ]

@hint

The @hint directive adds a type hint to some part of the FDL schema definition. Type hints are used to augment downstream type information for FDL in certain target systems.

FDL's string type is an arbitrary length string. Some downstream systems (most notably redshift) do not have downstream arbitrary length strings. You can use the length type hint on a string to change the default string length for these downstream systems:

aStringField : String! @hint(length: 500) ## This string will appear as varchar(500) in redshift

@is_default( out: output name)

Default values represent the current state of your application. The are changed by running experiments to test out new configurations, and by rolling out changes to subsets of your traffic. This directive will set the target to true if the given output is the current default, false if set by a running experiment or a partial rollout. The target of this directive must be a nullable boolean. See also @variant_id and @variant_name.

feature
{
   output {
       aString : String!
       aString_default: Boolean @is_default(out: "aString")
   }
}

@mutable

see Mutable Data

@no_gate

Remove the feature gate from the given feature.

@no_log

Do not write this field to the data warehouse. This is useful for PII data that you do not want to store, but needs to be available on the front ends. The field will appear as usual in the front end APIs, but will never be written to persistent storage.

@off_by_default

When added to a feature definition, causes the feature to be inactive unless someone explicitly activates it on the feature's web page.

Normally, features are immediately available once the code for the feature is deployed into a development environment. The default values for the feature's output are all accessible through the client APIs.

However, when @off_by_default is specified, the feature will instead be marked inactive and no values will be available.

@per

see Per Metrics

@persistent_key

see Persistent Keys

@session_key

see Session Keys

@split_key

see Splitting Traffic by User

@variant_id( out: output name)

If the given output was set by an experiment, return that variant's id. Null if the given output is set to the default value. See also @is_default and @variant_name.

feature
{
   output {
       aString : String!
       aString_variant_id: ID @variant_id(out: "aString")
   }
}

@variant_name( out: output name)

If the given output was set by an experiment, return that variant's name. Null if the given output is set to the default value. See also @is_default and @variant_id.

feature
{
   output {
       aString : String!
       aString_variant_id: String @variant_name(out: "aString")
   }
}

args

feature <feature name>
{
    args {
        [ "<description>" ]
        <arg name> : <arg type> [ = <default value> ] ...
    }
}

event

feature <feature name>
{
    [ "<description>" ]
    event
    {
        [ "<field description>" ]
        <field name> : <field type> [ = <default value> ] ...
    }
}

Declaring an event inside a feature will tie that event to that particular feature. Causal will automatically collect these events and put them on the feature impression's row.

session
{
    [ "<description>" ]
    event
    {
        [ "<field description>" ]
        <field name> : <field type> [ = <default value> ] ...
    }
}

Declaring an event at the session level will tie that event to the user session as opposed to and feature impression. Use this form to collect events that are not associated with a particular impression, but still are important for measuring success.

[ "<description>" ]
event
{
    [ "<field description>" ]
    <field name> : <field type> [ = <default value> ] ...
}

Defining an event at the top level will not actually allow you to signal the event. However, you may import it into a feature or session.

namespace

namespace <dotted name>;

The namespace keyword tells Causal what package or namespace to generate code in for languages that support it (currently Java and Avro schemas). If you have more that 1 Causal account in your organization, you can choose different namespaces so your code doesn’t conflict.

If no namespace is specified in the file, the default is io.causallabs.generated.

output

feature <feature name>
{
    output {
        [ "<description>" ]
        <output name> : <output type> = <default value> ...
    }
}

session

session {

    ## events can also be defined outside of features. A session event happens online
    ## while a user event can happen anywhere through a bulk upload mechanism
    "The user opened an email that we sent them"
    event open_email {
        campaign_id: String!
    }

    "The user used a discount code we provided"
    event used_discount_code {
        discount_code: String!
    }
}

Event may occur outside of features. These are defined at the session level, so are not tied to any feature impression. Instead they are just recorded on the user's session.