Datagraph Schema API

import assert from 'node:assert'

const API_BASE_URL = 'https://api.reelevant.com/v2'

type DatagraphColumn = {
  name: string
  type: string
  nullable: boolean
  default?: string | number | boolean | null
  description?: string
}

type DatagraphRelation = {
  type: 'Relation'
  columns: string[]
  reference: {
    datasourceId: string
    table: string
    columns: string[]
  }
  description?: string
}

type DatagraphTable = {
  name: string
  datasourceId: string
  description?: string
  columns: DatagraphColumn[]
  relations?: DatagraphRelation[]
  uniqueKeys?: { type: 'UniqueKey'; columns: string[] }[]
  indexes?: { type: 'Index'; columns: string[] }[]
}

type RelationAnalysisResult = {
  fromDatasourceId: string
  fromTable: string
  fromColumn: string
  fromDistinctCount: number | null
  toDatasourceId: string
  toTable: string
  toColumn: string
  toDistinctCount: number | null
  matchCount: number | null
  matchPercentage: number | null
  error?: string
}

type ValidateSchemaResponse = {
  validation:
    | { success: true; data: DatagraphTable[] }
    | { success: false; error: { issues: { path: (string | number)[]; message: string; code: string }[] } }
  relations: RelationAnalysisResult[]
}

const accessToken = process.env.REELEVANT_ACCESS_TOKEN
assert(accessToken, 'REELEVANT_ACCESS_TOKEN is required')

const productsDatasourceId = '8b53d7f1c2a94e6ea0b41d77'
const purchasesDatasourceId = '6a1f9c24e0b84f0f9a2d7c31'

const schema: DatagraphTable[] = [
  {
    name: productsDatasourceId,
    datasourceId: productsDatasourceId,
    description: 'Product catalogue',
    columns: [
      { name: 'reference_id', type: 'reference_id', nullable: false },
      { name: 'name', type: 'name', nullable: false },
      { name: 'price', type: 'price', nullable: true },
    ],
    uniqueKeys: [{ type: 'UniqueKey', columns: ['reference_id'] }],
  },
  {
    name: purchasesDatasourceId,
    datasourceId: purchasesDatasourceId,
    description: 'Purchase history',
    columns: [
      { name: 'user_id', type: 'string', nullable: false },
      { name: 'product_reference', type: 'string', nullable: false },
      { name: 'purchased_at', type: 'datetime_iso', nullable: false },
    ],
    relations: [
      {
        type: 'Relation',
        columns: ['product_reference'],
        reference: {
          datasourceId: productsDatasourceId,
          table: productsDatasourceId,
          columns: ['reference_id'],
        },
      },
    ],
  },
]

const response = await fetch(`${API_BASE_URL}/datagraph/schemas/validate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ schema }),
})

const payload = (await response.json()) as { status: string; data: ValidateSchemaResponse }

if (payload.data.validation.success === false) {
  for (const issue of payload.data.validation.error.issues) {
    console.error(`${issue.path.join('.')}: ${issue.message} (${issue.code})`)
  }
} else {
  for (const relation of payload.data.relations) {
    console.log(
      `${relation.fromTable}.${relation.fromColumn} → ${relation.toTable}.${relation.toColumn}: ` +
        `${relation.matchPercentage ?? 'n/a'}%`,
    )
  }
}

{
  "status": "success",
  "code": 200,
  "message": "ok",
  "data": {
    "validation": {
      "success": false,
      "error": {
        "issues": [
          {
            "path": [1, "relations", 0, "reference", "table"],
            "message": "Referenced table does not exist in the schema",
            "code": "custom"
          }
        ]
      }
    },
    "relations": []
  }
}

{
  "fromDatasourceId": "6a1f9c24e0b84f0f9a2d7c31",
  "fromTable": "6a1f9c24e0b84f0f9a2d7c31",
  "fromColumn": "product_reference",
  "fromDistinctCount": 12000,
  "toDatasourceId": "8b53d7f1c2a94e6ea0b41d77",
  "toTable": "8b53d7f1c2a94e6ea0b41d77",
  "toColumn": "reference_id",
  "toDistinctCount": 400000,
  "matchCount": 12000,
  "matchPercentage": 3
}

const publishResponse = await fetch(`${API_BASE_URL}/datagraph/schemas/${schemaId}/publish`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}` },
})

if (!publishResponse.ok) {
  const error = (await publishResponse.json()) as { message: string; code: number }
  throw new Error(`Publish failed (${error.code}): ${error.message}`)
}

const createResponse = await fetch(`${API_BASE_URL}/datagraph/schemas`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ schema }),
})

if (createResponse.status === 409) {
  const listResponse = await fetch(`${API_BASE_URL}/datagraph/schemas`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  })
  const { data: schemas } = (await listResponse.json()) as { data: { _id: string }[] }
  const existingSchemaId = schemas[0]._id

  await fetch(`${API_BASE_URL}/datagraph/schemas/${existingSchemaId}`, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ schema }),
  })
}