Règles de jointure des liens reference

Contexte : comment les arêtes sont trouvées habituellement

Un type de lien reference infère les arêtes par jointure par valeur : une propriété de l'objet source doit être égale à une colonne de l'objet cible. Par défaut, le moteur découvre automatiquement la colonne de jointure à l'aide d'une heuristique : il recherche un recouvrement de tokens entre le nom de la colonne source et les colonnes d'identité de la cible (les colonnes déclarées dans defineIdentityRule) ainsi que les colonnes columnMap hors identité de la liaison cible — les colonnes d'identité étant classées en premier. Ce sondage a été élargi dans cette version pour couvrir les colonnes columnMap en plus des colonnes d'identité.

Cela fonctionne bien lorsque les noms des colonnes source et cible ont un recouvrement de tokens clair, que la colonne cible soit ou non une colonne d'identité. Cela ne fonctionne pas lorsque :

• Les noms de colonnes ne se recouvrent pas alors que les valeurs correspondent sémantiquement — l'heuristique classe les candidates par recouvrement de tokens, de sorte que les colonnes sans token commun obtiennent un score nul et ne sont pas sondées.
• Les valeurs sont stockées dans des formats différents de chaque côté (par ex. ASN sous la forme "AS3215" contre 3215, cveId avec une casse différente) — l'heuristique utilise toujours l'égalité brute.

Dans ces cas, la découverte automatique produit soit 0 arête, soit de mauvaises arêtes — en silence, sans aucune erreur.

Déclarer une règle de jointure explicite

Ajoutez un objet join à defineLinkType(...). Le moteur l'utilise de manière déterministe et ignore entièrement la découverte automatique :

import { defineOntology, defineLinkType } from '@scrydon/sdk-authoring/ontologies'

defineLinkType({
  slug: 'VulnAffectsVendor',
  displayName: 'Vulnerability affects vendor',
  sourceTypes: ['Vulnerability'],
  targetTypes: ['NetworkOperatorVendor'],
  // No kind needed — "reference" is the default.
  join: {
    sourceColumn: 'vendorProject',   // column on the Vulnerability side
    targetColumn: 'vendorName',      // column on the NetworkOperatorVendor side
  },
})

vendorName n'est pas une colonne d'identité de NetworkOperatorVendor, si bien que la découverte automatique la manquerait. Déclarer join fixe le moteur sur exactement cette paire de colonnes.

Pourquoi cet exemple est important

Les enregistrements CISA KEV stockent le fournisseur concerné dans vendorProject. Le type d'objet NetworkOperatorVendor conserve son identifiant canonique dans vendorName — une propriété hors identité. Sans règle join explicite, l'heuristique sonde à la fois les colonnes d'identité et hors identité (classées par tokens), mais les résultats dépendent du recouvrement des noms et peuvent être non déterministes lorsque plusieurs colonnes sont candidates. Déclarer join fixe le moteur sur exactement cette paire de colonnes et rend l'inférence des arêtes déterministe.

Normalisation des valeurs

Si la même valeur logique est stockée dans des formats différents de chaque côté, utilisez normalize pour les rendre comparables au moment de la jointure :

defineLinkType({
  slug: 'AsPathUsesAsn',
  displayName: 'AS-path entry uses ASN',
  sourceTypes: ['AsPathEntry'],
  targetTypes: ['AutonomousSystem'],
  join: {
    sourceColumn: 'asnRaw',     // stored as "AS3215" (string with prefix)
    targetColumn: 'asNumber',   // stored as 3215 (integer or plain number string)
    normalize: 'digits',        // strip all non-digit characters before comparing
  },
})

La normalisation est appliquée aux deux côtés avant la comparaison. La jointure est une égalité standard après normalisation.

Exemple de casse des identifiants CVE

Certains flux stockent les identifiants CVE sous la forme CVE-2024-12345 et d'autres sous la forme cve-2024-12345. Normalisez en minuscules pour les traiter comme égaux :

defineLinkType({
  slug: 'ExploitTargetsCve',
  displayName: 'Exploit targets CVE',
  sourceTypes: ['Exploit'],
  targetTypes: ['CveRecord'],
  join: {
    sourceColumn: 'cveRef',
    targetColumn: 'cveId',
    normalize: 'lower',
  },
})

Quand déclarer join

Déclarez une règle join explicite lorsque :

• Les noms de colonnes n'ont aucun token en commun. La découverte automatique (élargie dans cette version pour sonder à la fois les colonnes columnMap d'identité et hors identité) classe les candidates selon les tokens partagés entre les noms des colonnes source et cible — si aucun token ne se recouvre, la paire obtient un score nul et n'est pas sondée, produisant 0 arête en silence.
• Les valeurs sont stockées dans des formats différents. L'heuristique utilise toujours l'égalité brute, de sorte que les différences de format (par ex. "AS3215" contre 3215, casse des identifiants CVE) nécessitent un join explicite avec normalize.
• La jointure découverte automatiquement est ambiguë. Lorsque plusieurs colonnes cibles partagent des tokens avec la colonne source, déclarez join pour rendre le choix explicite.

Vous n'avez pas besoin de join lorsque :

• Le nom de la colonne source a un recouvrement de tokens clair avec une colonne cible (d'identité ou columnMap hors identité) et que les deux côtés stockent les valeurs dans le même format.
• Les deux côtés utilisent le même nom de colonne et le même format.

Préférez la canonicalisation à l'ingestion lorsque c'est possible

normalize est destiné aux cas où vous ne maîtrisez pas le format source — par exemple, lorsque deux flux externes publient des ASN dans des formats différents.

Si vous maîtrisez bien la manière dont les valeurs sont ingérées (par ex. votre propre pipeline ETL alimente la table), la meilleure approche consiste à stocker les valeurs dans un format canonique des deux côtés au moment de l'ingestion. C'est plus rapide au moment de la requête, plus facile à comprendre, et cela évite une logique de normalisation cachée dans l'extension.

Règle empirique : corrigez les données à l'ingestion lorsque vous en êtes propriétaire ; n'utilisez normalize que lorsque ce n'est pas le cas.

Référence complète du schéma

join?: {
  sourceColumn: string   // Property slug on the source object type
  targetColumn: string   // Property slug on the target object type
  normalize?: 'trim' | 'lower' | 'digits'
}

Les liens de proximité ne sont pas concernés

Cette page porte sur les types de liens reference. Les types de liens de proximité (kind: "proximity") utilisent un mécanisme d'inférence d'arêtes entièrement différent — la distance géodésique — et n'utilisent pas du tout join. Consultez le guide Types de liens de proximité.

Pour aller plus loin