Pivot values
What is a pivot value
Context
Marble users are free to define the data model used in the decision engine, as best fits their use case and internal data.
While doing so, you will usually define links (similar to "foreign keys" in the language of databases). Links are always defined in the "one to one" or "many to one" direction, that is to say, a link is defined from an entity A to an entity B, so that there is either 0 or 1 of B for every A. (see previous pages).
The typical data model we like to think of is made of
transactions
accounts
companies
events
with the following links:
transactions->accounts
(transactions.account_id -> accounts.object_id
)accounts->companies
(accounts.company_id -> companies.object_id
)events->companies
(events.company_id -> companies.object_id
)
Examples
Examples will be in blue blocks such as this, based on the data model above.
Why a pivot value
Scenarios are executed on an entity, for instance a transaction or an account in the example above. Decisions and cases are then naturally related to a given instance of this entity.
A natural use case is to analyze events at the higher level, for instance analyze all alerts at the company level. In order to do so, you must be able to search and group decisions related to this common parent entity.
AML investigations
AML investigations are focusing on the account owner : we want to be able to search all the decisions relevant to a given company, whether the scenario was executed on a transaction, an account or the company object itself.
By defining a pivot value for the objects on the data model, you create the grouping key that can be used to filter or group decisions as required.
Definition of a pivot
A pivot is always defined relative to a base table from the data model. It can be defined in one of two ways:
- a field from the base table. The payload's value for this field is used to compute the value of the pivot for a decision.
- a link, or chain of links, moving up from the base table. The field used to compute the actual value of the pivot for a decision is then the foreign key of the last link in the chain (that is to say, the unique key on the table that is pointed to.
Only string values can be used as pivot values, and only one pivot can be defined for every base entity - at least for now.
Once a pivot has been defined for an entity, the value of the pivot will be automatically attached to every new decision from a scenario based on this entity. Note that the actual value of the pivot can be null
.
Definition
A pivot on the
transaction
object could be defined astransactions.partner_id
(a string field from thetransactions
entity), or alternatively astransactions.account
ortransactions.account.company
(chains of links pointing from thetransactions
entity to theaccounts
orcompanies
parents entity).
Applications using a pivot in Marble
Once you have defined a pivot on an entity in your data model, you open the possibility to:
- Search all decisions matching a given pivot value (e.g. searching all decisions on transactions or accounts for a given
company_id
) - See the most recent decisions with the same pivot value, on a decision details page
- Set up a workflow to try and attach a new decision to an existing open case, related to the same pivot value (e.g. attach a new decision on a
transaction
to an open or investigating case containing decisions with the same pivot valuecompany_id
). See documentation on workflows.
How to create a pivot in practice
A pivot is created from the data model edition page. Simply navigate to the graph view of your data model (https://app.checkmarble.com/data/schema, unless you are self-hosted). After having set up your tables and links, you can easily configure a pivot for any given base table by opening the options for this table and choosing the "create a pivot" option, as illustrated below.
Step by step:
![Start with a complete data model, including links](https://files.readme.io/2a44499-Capture_decran_2024-05-10_a_11.50.54.png)
Start with a complete data model, including links
![Select "Create a pivot" on the base table](https://files.readme.io/967866a-Capture_decran_2024-05-10_a_11.51.03.png)
Select "Create a pivot" on the base table
![Select a field from the base table, or a chain of named links, to define a pivot](https://files.readme.io/3e12d8c-Capture_decran_2024-05-10_a_11.51.12.png)
Select a field from the base table, or a chain of named links, to define a pivot
![A "view pivot details" button replaces the "Create a pivot" button in the table menu, that allows you to see visualize the pivot definition graphically.](https://files.readme.io/e7d93fa-Capture_decran_2024-05-10_a_11.51.26.png)
A "view pivot details" button replaces the "Create a pivot" button in the table menu, that allows you to see visualize the pivot definition graphically.
Repeat the steps above for the other tables, in this case accounts
and companies
.
Pivot on the table that is the pivot
It may make sense to define a pivot on the table's
object_id
field itself (or whatever field is used on the last link defining the pivot), for the table that is used as a pivot entity.For instance, in our example, defining a pivot for the
companies
table using theobject_id
field so that decisions oncompanies
(if any) are grouped with decisions ontransactions
andaccounts
.
How to use a pivot in practice
![See the pivot value on a decision, and use the link to...](https://files.readme.io/f0b3e30-Capture_decran_2024-05-10_a_12.00.39.png)
See the pivot value on a decision, and use the link to...
![... filter all the decisions that share the same pivot value, whatever the scenario or base object.](https://files.readme.io/0204ef3-Capture_decran_2024-05-10_a_12.05.41.png)
... filter all the decisions that share the same pivot value, whatever the scenario or base object.
Limitations
- You can only create one pivot per table.
- Pivots are (for now) create-only, so make sure to double check your input. You can contact us if you created a wrong pivot and want to fix it.
- When a pivot is created for a table, the pivot value is stored on every new decision created thereafter, but not on decisions that had been taken previously.
Updated 3 months ago