Relational data
How Avra RFM reads a relational database — its tables, the keys that link them, the names and values in its columns, and what each table's time means.
Avra RFM predicts over a relational database: the tables your systems already keep, linked by keys. You don’t flatten them into one wide row first, and you don’t build features. This page explains how the model reads that data, so you know what to send and why each part of it matters.
Tables, rows, and keys
A relational database keeps each kind of thing in its own table, with one row per thing: a row for each customer, a row for each account, a row for each payment. Every row has an identifier of its own, its primary key, and rows point at each other by carrying those identifiers as foreign keys. A payment carries the ID of the account it came from, and the account carries the ID of the customer who owns it.
Your database is a graph
Follow the keys and the tables turn into a graph. Each row is a node, and each key that points at another row is an edge. In the figure, customer C1 connects to accounts A1 and A2, and account A1 connects to payments P1 and P2. Nothing in the data changed: the graph is another way of reading the same rows.
That way of reading matters because most questions about a record depend on what’s connected to it. Whether customer C1 stops buying depends on its own payments, and also on the accounts they came from, the products in its orders, the tickets it opened, and how customers like it behaved. Following the edges from a record, one hop and then another, reaches everything related to it.
When the RFM makes a prediction about a record, it reads a sample of the rows connected to it this way, across the tables the keys reach, instead of a summary built in advance. That’s why there’s no feature table to build: the relationships stay in the data the model reads. See How predictions work.
Keys
Keys turn separate tables into one database, so they’re the part of your data that matters most. Each table that holds records needs a primary key, and every link needs a column whose values match the key it points at, written the same way in both tables. Identifiers can be legal documents, such as a CNPJ or a CPF, or your own keys.
The RFM learns the relationships from the keys, inferred from the data or declared when your pipeline is set up. A key written one way in one table and another way in the next, with and without punctuation, say, breaks the link, and the records on either side stop seeing each other. The ingestion pipeline’s checks can catch that before it reaches a model: when your contract declares the relationship check, a key that doesn’t resolve to a record blocks the run by default.
Names, text, and values
The RFM reads table names, column names, and text values as language, Portuguese included. A column named data_vencimento or valor_parcela carries its meaning without being renamed, and free-text fields, such as a ticket’s description or a transaction’s memo, are read as text.
Numbers, booleans, timestamps, and text are each read as what they are. There’s no encoding or scaling to do first, and a missing value is simply left out instead of being filled in.
What a table’s time means
Each table tells the model what its time means, and that choice decides what a prediction may see.
| Kind | The row’s time is | Examples |
|---|---|---|
| Static | None: the row’s values don’t change | A product catalog, a list of branches |
| Event | When the event happened, which is also when it became known | Purchases, logins, payments recorded as they happen |
| Available | When the row became known, which can be later than the business event it describes | Records that arrive late, snapshots of a value that changes |
A payment made on September 5 that reaches your warehouse on September 9 wasn’t known on September 7. A table whose rows can arrive late uses the time each row became known, and keeps the business date as an ordinary column that the model still reads. The ingestion pipeline keeps both times for every row, which is what makes that choice possible.
A row doesn’t inherit its parent’s time. Order lines with no time of their own would be visible before their orders, so give each line the time its order was placed, or the time the line arrived if that’s later.
Each timed table also declares how far its data is complete. An outcome counted over a window that runs past the end of the data isn’t the real outcome, so a target is computed only where every table it reads is complete through the end of its window.
What makes good relational data
Send the records you want to score and every table that touches them, even indirectly: the counterparties on a transaction, the products on an order, the owners of a company. A relationship the model can’t follow is signal it can’t use.
Keep the keys consistent across tables, and give every timed table an honest time, when each row became known if that differs from when it happened. Send enough history to hold past outcomes for the periods you want to evaluate on, and send the outcomes themselves as data, each with its date. Your Avra team reviews all of this with you during data discovery. See Preparing your data.