Quickstart

Step 1: Create your datamart function

mediarithmics will create new datamart functions for you, and they will be made available to all other customers. Please discuss your needs with your Account Manager.

Create a plugin and a version

Follow the standard procedure to create a plugin with the type "DATAMART_FUNCTION". Once the plugin is created, you can generate a version for it.

Create a build from the datamart function SDK

You are required to implement four key functions from the Datamart Function SDK and specify the build tag when deploying the plugin version.

OnUpdate functions

These functions are triggered during the initialization of the Datamart Function and whenever a new activity, profile update, or computed field modification occurs, updating the State accordingly.

// Trigger by a new activity
   onUpdateActivity(state: State, userActivity: UserActivity): State {...}

// Trigger by an update on the user profile
   onUpdateUserProfile(state: State, userProfile: UserProfile, operation: core.Operation): State {...}

//Trigger by the result of another computed field
  onUpdateComputedField(state: State, computedField: ComputedField): State {...}

The activities or profiles received by the plugin are raw data, so you can't rely on the structure defined in your schema to understand its design. However, you can refer to the structure outlined on the User Lookup page.

This function must be commutative to ensure consistency during initial loading, where event order is not guaranteed. It should always produce the same result, regardless of the sequence in which events are processed.

To prevent system overload, the State size is restricted to a maximum of 1 MB. If this limit is exceeded, the update will be discarded and not saved.

Although onUpdateComputedField has not been released yet, it is still required to be implemented in your plugin. In the meantime, simply return the State directly to avoid any errors.

BuildResult

This function returns the result of the Datamart function for a specific State. The Result will be stored for a defined duration, and querying the field will return the stored value during that period.

// To implement
   buildResult(state: State | null): Result {...}

Step 2: Create your computed field

1. In the Computing Console, navigate to Computed Fields.

2. Add a new computed field.

3. Select the plugin and version of the new instance you want to use.

4. Complete the necessary fields:

Fields	Description
Datamart	This is the context of the execution of the datamart function.
Name	Name of the computed field used in the interfaces (manager only)
Description	(Optional) Describe the computed field
Technical name	Name of the computed field used in the schema
Events filter	GraphQL selector query to filter the activity which will trigger the State updates
Maximum cache duration (in days)	Maximal duration before the periodic update of the State in days.

This will set up the computed field linked to your Datamart function for use in the system.

Step 3: Declare your computed field in your schema

After creating the computed field, you need to connect it to your schema:

1. Use the directive @ComputedField(technical_name = "...") at the appropriate level of your schema.

2. Ensure the technical name matches the one used when creating the computed field.

This will integrate the computed field into your schema and make it available for use in queries and operations.

// Example in your schema 
type UserPoint {
  id: ID!
  accounts: [UserAccount]
  …
  rfm_score: RfmScore @ComputedField(technical_name = “RfmScore”) @TreeIndex(index:"USER_INDEX")
}

type RfmScore {
  …
}

A schema validation will be triggered when you click Save. It will ensure that your Datamart has access to all the declared computed fields and verify their integration with the schema.

Step 4: Wait until the end of the initial loading

Once your schema is validated, our service will run a job to initialize your computed field and set the state to match the current status of the timeline. For each user point in your Datamart, we will process their timeline and execute the OnUpdateXXX() function.

To monitor the progress:

1. Go to the Computing Console > Computed Fields.

2. Check if your computed field is ready or if the initial loading is still in progress.

Please note, this process may take some time to complete as it computes the timelines for all user points.

Avoid using your computed field until the initial loading is complete. While the query will not return an error, the result may be inaccurate during this process.

Step 5: Use your computed field

Once the initial loading is complete, you can start using your computed field just like any other standard field in mediarithmics features.

For example, in query tools or any OTQL query:

SELECT { rfm_score } FROM UserPoint

If your computed field is indexed, you can also perform queries like:

SELECT { id } FROM UserPoint WHERE rfm_score = "PASSIVE"

This allows you to incorporate the computed field into your data analysis and queries once it's fully initialized.