Developer
User guidesDeveloper websiteHelp centerLog in
  • Welcome!
  • Organisations structure
    • Datamart
    • Users and roles
  • User points
    • User identifiers
      • Networks IDs
        • Device-based Network IDs
          • Custom Device ID integration
          • ID5
          • First ID
        • User-based Network IDs
          • Custom User ID integration
          • UTIQ martechpass
      • Accounts
      • Emails
      • Device identifiers
    • User activities and events
    • Compartments
    • User profiles
    • User segments
    • Hyper point & Quarantine
  • Data model
    • Defining your schema
    • Computed fields
      • Concepts
      • Setup
      • Development
      • Examples
  • Data ingestion
    • Real time user tracking
      • Website tracking
      • Mobile apps tracking
      • Ads exposure tracking
      • AMP tracking
      • Conversions tracking
      • Email views and clicks
      • Tracking API
      • Event rules
      • Activity analyzers
    • Bulk processing
      • Imports
        • User activities import
        • User profiles import
        • User choices import
        • Segments import
      • Deletions
        • User identifiers deletion
        • Device points deletion
        • User points deletion
      • User identifiers association
      • Integration batch
    • Activities analytics
    • Data warehouse
      • Preliminary setup
        • BigQuery
      • Create data warehouse
  • Querying your data
    • OTQL queries
    • OTQL examples
    • GraphQL queries
    • UserPoint API
    • User activities
    • Activities analytics queries
      • API Quickstart
      • Dimensions and metrics
      • Use cases
    • Funnel API
  • Alerting
    • Alert configurations
  • Data visualisation
    • Quickstart
    • Dashboards
    • Sections and cards
    • Charts
    • Datasets and data sources
      • Using a data file data source
    • Transformations
    • Filters
    • Cookbook
    • Reference
  • Advanced usages
    • Audience segmentation
      • Audience features
      • Segment builders
      • Audience segment metrics
      • Audience segment feed
        • Building new feeds
        • Monitoring a feed
        • Curated Audiences (SDA)
      • Edge segments
      • Cohort-based Lookalike
    • Contextual targeting
      • Setup
      • Activation
        • Google Ad Manager
        • Xandr (through prebid.js)
      • API documentation
    • Exporting your data
      • Query Exports
      • Datamart replication
    • Data privacy compliance
      • User choices
      • Cleaning rules
      • Exercise of user rights
      • Cookies
    • Campaigns
    • Automations
      • Email routers
      • Email renderers
      • Opt-in provider
      • Custom action plugins
      • Usage limits for automations
    • Plugins
      • Concepts
      • Creation & Deployment
      • Coding your plugin
      • Manage existing plugins
      • Layouts
      • Presets
      • Monitoring
      • Throttling
      • Batching (for external feeds)
    • Platform monitoring
      • Resources usage
        • Dimensions and metrics
      • Collection volumes
        • Dimensions and metrics
      • Events ingestion monitoring
        • Dimensions and metrics
    • Data Clean Room
      • Bunker
      • Clean room
  • Resources
    • Tutorial: Data Ingestion
      • Your first events
        • Add the mediarithmics tag
          • Getting the tag
          • Adding the tag
        • Send events using the tag
          • Adding event properties
          • Finding the UserEvent type in your schema
          • Matching your schema
          • Standard events
      • Your first bulk imports
        • API basics
          • Authentication
          • Your first API call
        • Send documents using the API
          • Requirements
          • Sending documents
    • Using our API
      • Authentication
    • Tools & libraries
      • mics CLI
      • JS Tag
      • Plugin SDK
    • Data cubes
      • Creating a report
      • Reference
Powered by GitBook
On this page
  • Schema publication workflow
  • Schema updates
  • Manage schemas with mics CLI
  • Download a schema
  • Update a schema
  • Get existing schemas
  • Get a schema
  • Get the content of a schema
  • Create a DRAFT by cloning
  • Create a DRAFT without cloning
  • Upload the content
  • Validate a DRAFT schema
  • Publish a schema

Was this helpful?

Export as PDF
  1. Data model

Defining your schema

PreviousData modelNextComputed fields

Last updated 3 months ago

Was this helpful?

are associated with by managing objects with the following properties:

Make sure you learned about .

// DRAFT Schema
{
    "id": "1385",
    "datamart_id": "1509",
    "status": "DRAFT",
    "creation_date": 1609888013947,
    "last_modification_date": 1610443926552,
    "publication_date": null,
    "suspension_date": null
}

// LIVE Schema
{
    "id": "1281",
    "datamart_id": "1509",
    "status": "LIVE",
    "creation_date": 1603198414771,
    "last_modification_date": 1603198415117,
    "publication_date": 1603198415733,
    "suspension_date": null
}
        
// ARCHIVED Schema
{
    "id": "1276",
    "datamart_id": "1509",
    "status": "ARCHIVED",
    "creation_date": 1603102827888,
    "last_modification_date": 1603102828087,
    "publication_date": 1603102828479,
    "suspension_date": 1603102848269
}

Schema publication workflow

The process for publishing a schema is as follows:

  1. Create a new schema definition

  2. Upload the schema associated with the definition

  3. Validate the schema

  4. Publish the schema

Schema updates

If you remove an indexed property, you will instantly stop being able to run WHERE queries and operators needing indexing for this query.

You can ask your mediarithmics contact to start a complete reindexing of your datamart if required

Manage schemas with mics CLI

Download a schema

Retrieve the LIVE schema or the specified one for a given datamart, and save it as a .gql file named schema-<DATAMARTID>-<SCHEMAID>.gql.

Use it to download the schema you want to start with, usually the current LIVE version.

USAGE
  $ mics-cli schema:fetch DATAMARTID [SCHEMAID]

ARGUMENTS
  DATAMARTID  the ID of the datamart
  SCHEMAID    [default: LIVE] the ID of the schema, or LIVE to get the live schema

OPTIONS
  --stdout  output the content of the file instead of saving it in a file

If you want to show the schema in the output, use the --stdout flag.

Update a schema

Create a draft, upload a file, validate it, and publish the schema with this all-in-one command.

  • If a draft schema already exists, update it before publishing.

  • Latest LIVE schema is cloned, if available, and --noClone flag is not set

You can keep your schema as a DRAFT and not publish it using the --skipPublishflag.

Get existing schemas

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/graphdb_runtime_schemas

Returns all schemas and their status.

Path Parameters

Name
Type
Description

datamartId

integer

The ID of the datamart

{
    "status": "ok",
    "data": [
        {
            "id": "1266",
            "datamart_id": "1509",
            "status": "ARCHIVED",
            "creation_date": 1602860201358,
            "last_modification_date": 1602860221562,
            "publication_date": 1602860275189,
            "suspension_date": 1602860362588
        },
        {
            "id": "1281",
            "datamart_id": "1509",
            "status": "LIVE",
            "creation_date": 1603198414771,
            "last_modification_date": 1603198415117,
            "publication_date": 1603198415733,
            "suspension_date": null
        },
        {
            "id": "1385",
            "datamart_id": "1509",
            "status": "DRAFT",
            "creation_date": 1609888013947,
            "last_modification_date": 1610443926552,
            "publication_date": null,
            "suspension_date": null
        }
    ],
    "count": 3,
    "total": 3,
    "first_result": 0,
    "max_result": 2147483647,
    "max_results": 2147483647
}

Archived schemas are displayed, meaning you can watch your history

Get a schema

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/graphdb_runtime_schemas/:schemaId

Path Parameters

Name
Type
Description

datamartId

integer

The ID of the datamart

schemaId

integer

The ID of the schema

{
    "status": "ok",
    "data": {
        "id": "1266",
        "datamart_id": "1509",
        "status": "ARCHIVED",
        "creation_date": 1602860201358,
        "last_modification_date": 1602860221562,
        "publication_date": 1602860275189,
        "suspension_date": 1602860362588
    }
}

Get the content of a schema

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/graphdb_runtime_schemas/:schemaId/text

Allows you to visualize how your schema is in the current version, or how it has been in archived versions

Path Parameters

Name
Type
Description

datamartId

string

The ID of the datamart

schemaId

integer

The ID of the schema

##


type UserPoint  @TreeIndexRoot(index:"USER_INDEX") {
   events:[ActivityEvent!]!
   creation_ts:Timestamp! @TreeIndex(index:"USER_INDEX")
   id:ID!
}

##


type ActivityEvent  {
   referrer:String @TreeIndex(index:"USER_INDEX") @Property(path:"$properties.$referrer")
   url:String @TreeIndex(index:"USER_INDEX") @Property(path:"$properties.$url")
   date:Date! @TreeIndex(index:"USER_INDEX") @Function(params:["ts"], name:"ISODate")
   nature:String @Property(path:"$event_name") @TreeIndex(index:"USER_INDEX")
   ts:Timestamp!
   id:ID!
}

Create a DRAFT by cloning

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/graphdb_runtime_schemas/:schemaId/clone

Creates a new DRAFT schema if there's no existing one, by cloning an existing one.

Path Parameters

Name
Type
Description

schemaId

integer

The ID of the schema to clone. Usually the current LIVE version.

datamartId

integer

The ID of the datamart

{
    "status": "ok",
    "data": {
        "id": "1395",
        "datamart_id": "1509",
        "status": "DRAFT",
        "creation_date": 1610449867207,
        "last_modification_date": 1610449867207,
        "publication_date": null,
        "suspension_date": null
    }
}
{
    "status": "error",
    "error": "Impossible to create a new schema, there is already one draft schema",
    "error_code": "CONSTRAINT_VIOLATION_EXCEPTION",
    "error_id": "690596a9-b0e0-43b3-88e8-b90d08b98029"
}

This is the preferred method to create a DRAFT schema, as it will keep all settings from the previous version, like cluster versions, and index sizes.

Create a DRAFT without cloning

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/graphdb_runtime_schemas

Creates a new DRAFT schema if there's no existing one without cloning.

Path Parameters

Name
Type
Description

datamartId

integer

The ID of the datamart

{
    "status": "ok",
    "data": {
        "id": "1395",
        "datamart_id": "1509",
        "status": "DRAFT",
        "creation_date": 1610449867207,
        "last_modification_date": 1610449867207,
        "publication_date": null,
        "suspension_date": null
    }
}
{
    "status": "error",
    "error": "Impossible to create a new schema, there is already one draft schema",
    "error_code": "CONSTRAINT_VIOLATION_EXCEPTION",
    "error_id": "690596a9-b0e0-43b3-88e8-b90d08b98029"
}

For the schema to keep initial settings—for example, elastic search version, and index size—you need to clone the previous LIVE version. Only use this endpoint if you know the required settings and you can set them up before publishing.

Upload the content

PUT https://api.mediarithmics.com/v1/datamarts/:datamartId/graphdb_runtime_schemas/:schemaId/text

Add the schema to content to the raw body of the request

Path Parameters

Name
Type
Description

datamartId

integer

The ID of the datamart

schemaId

integer

The ID of the schema

Request Body

Name
Type
Description

body

string

Raw schema to upload

{
    "status": "ok"
}

Validate a DRAFT schema

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/graphdb_runtime_schemas/:schemaId/validation

Tells you if the uploaded schema is valid, and shows errors if there are any.

Path Parameters

Name
Type
Description

datamartId

integer

The ID of the datamart

schemaId

integer

The ID of the schema

{
    "status": "ok",
    "data": {
        "datamart_id": "1509",
        "schema_id": "1266",
        "tree_index_operations": [
            {
                "datamart_id": "1509",
                "index_selection_id": "2121",
                "index_name": "USER_INDEX",
                "init_strategy": "FORCE_NO_BUILD",
                "driver_version_major_number": 1,
                "driver_version_minor_number": 2,
                "current_index_id": "574",
                "current_index_size": "SMALL",
                "new_index": false,
                "new_index_size": "SMALL",
                "init_job": null,
                "error_code": null,
                "error_message": null
            }
        ],
        "schema_errors": []
    }
}
{
    "status": "error",
    "error": "2 error(s) found when validating schema : Type 'UserPoint' which is root of tree index 'USER_INDEX' requires a scalar field named 'creation_ts' to be annotated with '@TreeIndex(index:\"USER_INDEX\")' and to be typed 'Timestamp!', Type 'UserAccount' which is root of tree index 'USER_INDEX' requires a scalar field named 'compartment_id' to be annotated with '@TreeIndex(index:\"USER_INDEX\")' and to be typed 'String!'",
    "error_code": "BAD_REQUEST_DATA",
    "error_id": "6a52cea9-6de4-40f5-972e-a8480c268d19"
}

Publish a schema

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/graphdb_runtime_schemas/:schemaId/publication

The selected schema goes LIVE, and the actual LIVE schema is ARCHIVED. Will show an error if you didn't validate the schema.

Path Parameters

Name
Type
Description

datamartId

integer

The ID of the datamart

schemaId

integer

The ID of the datamart

{
    "status": "ok",
    "data": {
        "datamart_id": "1509",
        "schema_id": "1395",
        "tree_indices": [
            {
                "index_name": "USER_INDEX",
                "new_index": false,
                "index_id": "574",
                "index_size": "SMALL",
                "init_strategy": "FORCE_NO_BUILD",
                "driver_version_major_number": 1,
                "driver_version_minor_number": 2,
                "init_job": null
            }
        ]
    }
}
{
    "status": "error",
    "error": "Impossible to publish schema, validate the schema before a new publication",
    "error_code": "BAD_REQUEST_DATA",
    "error_id": "76e70020-02cb-40ec-8109-adf204aa0a7b"
}

After updating a schema, you can immediately use all its properties into the select part of your and any operator that doesn't require indexing.

If you add a new indexed property, only new elements going into your datamart will be indexed. You will be able to run WHERE queries and operators needing indexing, but your queries will not return values for elements already in your datamart. You can add a new indexed property by either adding a new property with or adding the @TreeIndex directive to an existing property.

You can use the to power up your schema definitions workflow.

Automatically handles status and :

Schemas
datamarts
schema's concepts and how they are structured
OTQL queries
MICS CLI
cloning best practices
@TreeIndex directive