External Outputs

Causal features include outputs that can be set based on feature rollouts or experiments. For more complicated experiments, you may want these values passed in from your current architecture, as opposed to being calculated inside the Causal feature.

For example, let's say that you are experimenting with your site's search algorithm. One simple way to do this is with Causal's Elastic Search Integration, which is a quick way to get Elastic results up to your website while also collecting training data.

However, let's say that you already have a microservice to calculate the results and feed them to the front end. You'd like to use Causal to collect data and run experiments, but not disrupt any of the current code.

External outputs are designed for this case. Take a look at the following feature definition.

feature search_page {
    args {
        query_string: String!
    }
    output {
        documents : [{
            id : String!
            title : String!
            body : String!
        }] = [] @external( values: ["popularity", "distance"] )
    }
    event click {
        id : String!
    }
}

The feature takes a search string, returns a list of documents, and records which documents get a click. A data scientist looking at your data warehouse would have all they need to put together a ranking model.

The @external directive creates a new enumeration with the values popularity, distance, and none. In the tools UI, this enumeration can be used for feature flagging and experimentation. When a value other than none is set, Causal passes it to your current code and expects the value of the output to be set by you using the Causal API.

Your current code then uses the enum value (i.e. popularity or distance) to calculate the list of documents as usual, and passes them back to Causal so they can be logged for use by your data scientists.

Just because an output has an external directive, does not mean the data must use this mechanism. Let's say that at some point you want to try Causal's built in integration with Elastic Search. As long as your Elastic query conforms to the schema specified in the output, you can have your application support both the external outputs and the off-the-shelf Elastic integration. That way, you can move your algorithm onto the built in integration at your leisure (or not at all).

All externals must be nullable values. If Causal never gets the callback to set the external, it will write a null into the warehouse for that impression.

API Only External Outputs

You can also specify an external output without any values. Take response_time, in the example below:

feature search_page {
    args {
        query_string: String!
    }
    output {
        documents : [{
            id : String!
            title : String!
            body : String!
        }] = [] @external( values: ["popularity", "distance"] )
        responseTime : Int @external
    }
    event click {
        id : String!
    }
}

In this case, you will still have the setters in the client APIs, but you won't be able to select a value from the Tools UI. In fact, responseTime will not appear as a settable option in the feature or experiment pages. This kind of external is useful for logging information along with the impression that is not available at the time the impression is created. The external API allows you to set the value at a later time.