Aller au contenu principal

Structurer votre fichier de définition JSON

Description des informations constituant votre fichier de définition

Pour créer votre table personnalisée du modèle de données, il sera nécessaire de définir sa structure par le biais d'un fichier JSON.

Ce fichier JSON doit contenir une série d’informations. Certaines de ces informations sont obligatoires, d’autres sont optionnelles. De plus, elles peuvent avoir certaines contraintes à respecter, soit au niveau de leur typage, soit au niveau des valeurs possibles.

astuce

La structure du fichier JSON est la même que le payload des appels API effectués pour créer une table.

Vous pouvez trouver un guide détaillé sur le portail des développeurs.

Illustration d'un fichier JSON complet

Le fichier suivant fournit une illustration du format que prend un fichier contenant tous les paramètres possibles, avec des valeurs d'exemple.

Illustration visuelle d'un fichier de définition JSON

{
"name": "OnlineOrders",
"entityName": "entity",
"type": "INTERACTIONS",
"primaryKeyAttribute": "orderId",
"creationTimeAttribute": "orderMoment",
"compositeKey": null,
"bigTable": false,
"attributes": [
{
"name": "orderId",
"valueType": "STRING",
"mandatory": true,
"indexed": true,
"unique": true,
"valueRestriction": {
"minLength": 20,
"maxLength": 20
}
},
{
"name": "storeId",
"valueType": "LONG",
"mandatory": true,
"indexed": true,
"unique": false,
"valueRestriction": null
},
{
"name": "customerId",
"valueType": "LONG",
"mandatory": true,
"indexed": true,
"unique": false,
"valueRestriction": null
},
{
"name": "orderMoment",
"valueType": "TIMESTAMP",
"mandatory": true,
"indexed": true,
"unique": false,
"valueRestriction": null
},
{
"name": "amount",
"valueType": "NUMBER",
"mandatory": true,
"indexed": false,
"unique": false,
"valueRestriction": null
},
{
"name": "status",
"valueType": "STRING",
"mandatory": true,
"indexed": true,
"unique": false,
"valueRestriction": {
"acceptedValues": [
"NEW",
"SHIPPING",
"SHIPPED",
"CANCELED"
]
}
}
],
"valueAttribute": "amount",
"foreignKeys": [
{
"name": "link-to-customer",
"attribute": "customerId",
"reference": {
"tableType": "PROFILE_TABLE",
"tableId": "97",
"attribute": "customerId"
},
"onDelete": "CASCADE"
},
{
"name": "link-to-store",
"attribute": "storeId",
"reference": {
"tableType": "CUSTOM_TABLE",
"tableId": "d4d85214-66d4-4072-b98b-a86c9253b980",
"attribute": "storeId"
},
"onDelete": "CASCADE"
}
],
"eventsToTrigger": [
{
"name": "shipped-online-order",
"triggerRules": [
{
"onOperation": "UPDATE",
"onAnyAttribute": [
"status"
],
"onMatchingState": {
"stateBeforeOperation": {
"logicalOperator": "AND",
"predicates": [
{
"attribute": "status",
"operator": "!=",
"value": "SHIPPED"
}
]
},
"stateAfterOperation": {
"logicalOperator": "AND",
"predicates": [
{
"attribute": "status",
"operator": "=",
"value": "SHIPPED"
}
]
}
}
}
]
}
],
"cleaningRules": {
"oldestRecordsRule": {
"numberOfRecordsToKeep": 200000
}
},
"displayOptions": {
"displayName": "Online Orders",
"description": "The table that hosts the orders from an online store. Those orders are linked to the Customers profile table.",
"forAttributes": [
{
"name": "orderId",
"description": "The unique id of the order",
"displayName": "Online Orders ID"
},
{
"name": "storeId",
"description": "The unique id of the online store on which the order has been created.",
"displayName": "Store ID"
},
{
"name": "customerId",
"description": "The unique id of customer who has created the order.",
"displayName": "Customer ID"
},
{
"name": "orderMoment",
"description": "The moment when the order has been created",
"displayName": "Order Moment"
},
{
"name": "amount",
"description": "The amount of the order",
"displayName": "Amount"
},
{
"name": "status",
"description": "The status of the order",
"displayName": "Status"
}
],
"forEvents": [
{
"name": "shipped-online-order",
"displayName": "Shipped Online Order"
}
],
"layout": {
"defaultAttributes": [
"orderId",
"customerId",
"amount",
"status"
],
"sections": [
{
"displayName": "Identifiers",
"attributes": [
"orderId",
"customerId",
"storeId"
]
},
{
"displayName": "Other attributes",
"attributes": [
"amount",
"status",
"orderMoment"
]
}
]
}
}
}

Typage des champs

Selon leur typage, les champs devront respecter certaines contraintes :

  • STRING : séquence de caractères [a-z, A-Z, 0-9]

    • le nombre maximum de caractères pour le typage STRING est de 255. Cela peut être modifié avec un paramètre "typeValidator" (voir le tableau ci-dessus)
  • LONG :

    • un entier de 64bits

    • valeur maximale : 9223372036854775808

    • valeur minimale: -9223372036854775808

    • pas d’espace, ni de point, ni de virgule

  • BOOLEAN : respecter les valeurs suivantes “true” ou “false”

  • DATE : chaine de caractères répondant à un des formats suivants :

    • YYYYMMDD

    • YYYY-MM-DD

    • dd/MM/yyyy

  • TIMESTAMP : chaine de caractères répondant à un des formats suivants :

    • YYYYMMDD *

    • YYYY-MM-DD *

    • dd/MM/yyyy *

    • YYYYMMDDhhmmss

    • YYYY-MM-DD hh:mm:ss

    • dd/MM/yyyy HH:mm:ss

    • MM/dd/yyyy hh:mm:ss AM|PM

* si pas de valeur pour hhmmss, seront ajoutées les valeurs 00:00:00

  • NUMERIC :

    • le séparateur doit être un .

    • pas de limite de nombre de caractère

A savoir

En plus du typage général, il existe un typage avancé pour certains champs, afin de s'assurer que leur format corresponde au format attendu par Actito.

Il s'agit des types "EMAIL_ADDRESS","SEX","COUNTRY","LANGUAGE","PHONE_NUMBER","CIVIL_STATE". La syntaxe imposée pour ces types est détaillée dans la page "Utiliser les attributs prédéfinis".

Pour imposer qu'un champ de votre table corresponde à un de ces types, il sera nécessaire de le spécifier dans le paramètre "objectType".

Index de la table

A la création d’un champ, un index peut être utilisé pour aider Actito à trouver et trier les données plus rapidement.

Qu’est-ce que l'index ?

Un index stocke l’emplacement des enregistrements sur la base des champs qui ont été indexés. Une fois qu’Actito a obtenu l’emplacement à partir de l’index, il peut extraire les données en accédant directement à l’emplacement approprié. Ainsi, pour trouver des données, le fait d’avoir utilisé un index permet d’être sensiblement plus rapide.

Il est donc utile d’indexer des champs sur lesquels des recherches, des tris ou des ciblages sont fréquemment effectuées, ou à tout champ qui est associé à d’autres tables (clé de rapprochement avec l’autre table)

Par exemple, il est pertinent d’indexer les champs suivant d’une table : business key + foreign key + date de création.

Attention

Si les champs indexés peuvent accélérer les recherches et ciblages, ils peuvent aussi ralentir les performances lorsque des données sont créés ou mises à jour.

En effet, dans ces cas-là, Actito va devoir mettre à jour tous les index de la table. Il faut donc limiter le nombre de champs indexés dans une table.

Une table personnalisée ne peut pas dépasser 15 champs indexés.

Veuillez noter qu'un champ "unique" sera automatiquement indexé et que les champs "id", "creationMoment" et "updateMoment" sont créés automatiquement et indexés par défaut.