Requêtes

Les requêtes Mercator permettent d'explorer et de visualiser les données de votre cartographie de manière flexible, sans passer par l'interface standard. Elles s'écrivent dans un langage déclaratif inspiré du SQL et peuvent produire une liste ou un graphe.

Format d'une requête

Une requête Mercator suit la syntaxe suivante :

FROM    <Modèle>
FIELDS  <champ1>, <champ2>, <relation.champ>, ...
WHERE   (<condition1>) AND|OR (<condition2>)
WITH    <relation1>, <relation2>, ...
OUTPUT  list | graph
LIMIT   <n>

Clause	Obligatoire	Description
FROM	✅	Modèle de données cible (voir Modèles disponibles)
FIELDS	➖	Liste des champs à afficher, y compris les champs de relations (relation.champ)
WHERE	➖	Filtre sur les données (voir Conditions)
WITH	➖	Relations à charger en eager loading
OUTPUT	➖	Format de sortie : list ou graph (list par défaut)
LIMIT	➖	Nombre maximum d'enregistrements retournés (défaut : 100)

Modèles disponibles

Les modèles correspondent aux entités de l'API Mercator et sont en kebab-case.

Modèle	Description
logical-servers	Serveurs logiques
physical-servers	Serveurs physiques
applications	Applications
databases	Bases de données
certificates	Certificats SSL/TLS
networks	Réseaux / sous-réseaux
storage-devices	Dispositifs de stockage
sites	Sites physiques
bays	Baies d'hébergement
…	Tous les modèles de l'API

Champs disponibles

Les champs utilisables dans FIELDS et WHERE sont ceux exposés par l'API Mercator. Consultez le modèle de données pour connaître l'ensemble des attributs de chaque modèle.

Clause FIELDS

La clause FIELDS liste les attributs à afficher dans le résultat. Elle accepte :

• Les champs directs du modèle : name, cpu, environment, end_validity, …
• Les champs de relations au format relation.champ : applications.name, site.name, databases.name, …

FIELDS name, operating_system, cpu, memory, applications.name

Champs protégés

Les champs marqués comme cachés dans les modèles ($hidden Eloquent), tels que password ou remember_token, ne sont jamais retournés par le moteur de requêtes, même s'ils sont explicitement listés dans FIELDS.

Cohérence avec WITH

Si vous référencez un champ de relation dans FIELDS (ex. applications.name), la relation correspondante doit être déclarée dans WITH (ex. WITH applications), sans quoi les données ne seront pas chargées.

Clause WHERE

La clause WHERE filtre les enregistrements selon des conditions sur les champs du modèle principal.

Opérateurs supportés

Opérateur	Syntaxe	Exemple
Égalité	=	environment = "production"
Inégalité	!=	type != "virtual"
Comparaison	<, >, <=, >=	memory >= 16
Recherche	LIKE	operating_system LIKE "%Linux%"
Liste de valeurs	IN	environment IN ("production", "staging")
Existence de relation	EXISTS	EXISTS applications
Absence de relation	NOT EXISTS	NOT EXISTS certificates

Combinaisons logiques

Les conditions peuvent être combinées avec AND et OR. Chaque condition doit être encadrée par des parenthèses :

WHERE (environment = "production") AND (operating_system LIKE "%Linux%")

WHERE (environment IN ("production", "staging")) AND (operating_system LIKE "%Windows%")

Opérateur EXISTS

L'opérateur EXISTS filtre les enregistrements selon qu'une relation est présente ou absente. Il s'applique au nom de la relation Eloquent (tel que déclaré dans WITH).

WHERE (EXISTS applications)

WHERE (NOT EXISTS certificates)

EXISTS peut être combiné avec d'autres conditions :

WHERE (environment = "production") AND (EXISTS certificates)

EXISTS et eager loading

L'opérateur EXISTS n'implique pas le chargement des données de la relation. Si vous souhaitez également afficher les champs de cette relation dans FIELDS, déclarez-la explicitement dans WITH.

Clause WITH

La clause WITH déclare les relations à charger (eager loading). Elle est indispensable pour accéder aux champs d'objets liés dans FIELDS.

WITH applications, databases, certificates

Les noms de relations correspondent aux noms des méthodes de relation des modèles Eloquent, en snake_case :

WITH logical_servers, databases, sites, bays

Nœuds intermédiaires masqués

Par défaut, chaque segment d'un chemin WITH crée un nœud dans le graphe. Il est possible de masquer un niveau intermédiaire en l'entourant de parenthèses : le niveau est alors traversé pour accéder aux niveaux suivants, mais il n'apparaît ni comme nœud ni comme arête dans le graphe résultant.

WITH (subnetworks).vlan

Dans cet exemple, les sous-réseaux servent uniquement de pivot de traversée. Le graphe affiche directement des arêtes networks → vlan, sans représenter les subnetworks.

La syntaxe se généralise à plusieurs niveaux masqués :

-- Masquer un niveau sur deux
WITH (subnetworks).routers.(interfaces).vlan

-- Masquer plusieurs niveaux consécutifs
WITH (subnetworks).(routers).vlan

Les règles à respecter :

• Un chemin entièrement masqué (tous les segments entre parenthèses) est sans effet.
• Le dernier segment d'un chemin ne peut pas être masqué.
• Les parenthèses imbriquées ((rel)) sont interdites.

Quand masquer un niveau ?

Masquez un intermédiaire lorsque la relation pivot n'a pas de valeur sémantique dans la visualisation — par exemple, les sous-réseaux entre un réseau et ses VLANs, ou les interfaces entre un serveur et ses VLANs.

Format de sortie (OUTPUT)

OUTPUT list

Génère un tableau avec une ligne par enregistrement. C'est le format adapté pour les inventaires, les exports, ou les vues tabulaires.

OUTPUT list

OUTPUT graph

Génère un graphe de relations entre les entités retournées. C'est le format adapté pour visualiser les dépendances, les cartographies applicatives ou les relations réseau.

OUTPUT graph

Quand utiliser graph ?

Préférez OUTPUT graph dès que votre requête charge des relations avec WITH et que vous souhaitez visualiser les liens entre entités (applications ↔ serveurs, réseaux ↔ serveurs, etc.).

Sauvegarde des requêtes

Il est possible de sauvegarder des requêtes dans l'interface pour les retrouver et les réexécuter sans les ressaisir. Les requêtes sauvegardées peuvent être rendues publiques (visibles par tous les utilisateurs) ou privées (visibles uniquement par leur auteur).

Exemples

Serveurs Linux en production avec leurs applications

FROM logical-servers
FIELDS name, operating_system, environment, cpu, memory, applications.name
WHERE (environment = "production") AND (operating_system LIKE "%Linux%")
WITH applications

Retourne la liste des serveurs logiques sous Linux en environnement de production, avec le nom des applications hébergées.

Toutes les applications et leurs bases de données

FROM applications
FIELDS name, description, databases.name, logical_servers.name
WITH databases, logical_servers
OUTPUT graph

Génère un graphe reliant les applications à leurs bases de données et serveurs logiques.

Inventaire des serveurs physiques

FROM physical-servers
FIELDS name, type, cpu, memory, site.name, bay.name
WITH site, bay

Liste complète des serveurs physiques avec leur localisation (site et baie).

Réseaux, sous-réseaux et VLANs

FROM networks
FIELDS name, subnetworks.name, subnetworks.vlan.id, subnetworks.vlan.name
WITH subnetworks, subnetworks.vlan

Visualise les réseaux, sous-réseaux et leurs VLANs.

Réseaux et VLANs sans les sous-réseaux intermédiaires

FROM networks
WITH (subnetworks).vlan
OUTPUT graph

Génère un graphe reliant directement chaque réseau à ses VLANs. Les sous-réseaux servent de pivot de traversée mais n'apparaissent pas dans le graphe — utile pour obtenir une vue synthétique lorsque les sous-réseaux n'apportent pas d'information supplémentaire dans la visualisation.

Filtres multiples avec IN

FROM logical-servers
FIELDS applications.name, certificates.name
WHERE (environment IN ("production", "staging")) AND (operating_system LIKE "%Windows%")
WITH applications, certificates

Liste les applications et certificats installés sur les serveurs Windows en production ou en staging.

Certificats SSL avec date d'expiration et périmètre d'installation

FROM certificates
FIELDS name, type, end_validity, domains, logical_servers.name, applications.name
WITH logical_servers, applications

Inventaire des certificats SSL/TLS avec leur date d'expiration et les serveurs/applications sur lesquels ils sont déployés. Utile pour anticiper les renouvellements.

Applications critiques avec leurs serveurs et bases de données

FROM applications
FIELDS name, security_need_c, description, responsible, logical_servers.name, databases.name
WHERE (security_need_c IN ("3", "4"))
WITH logical_servers, databases
OUTPUT graph

Cartographie des applications à fort besoin de confidentialité (niveaux 3 et 4), avec leurs dépendances d'infrastructure.

Serveurs sans certificat SSL

FROM logical-servers
FIELDS name, environment, operating_system
WHERE (environment = "production") AND (NOT EXISTS certificates)
WITH certificates

Identifie les serveurs de production sur lesquels aucun certificat SSL/TLS n'est enregistré. Utile pour détecter des angles morts dans la gestion des certificats.

Serveurs en production sans plans de backups avec une application

FROM logical-servers
FIELDS name, applications.name
WHERE environment = "production"
AND NOT EXISTS backups
AND EXISTS applications
OUTPUT list

Identifier les serveurs et le nom des applications en production qui n'ont pas de plans de backups et au moins une application.

Applications sans serveur logique associé

FROM applications
FIELDS name, responsible, security_need_c
WHERE (NOT EXISTS logical_servers)
WITH logical_servers

Liste les applications non rattachées à un serveur logique, symptôme possible d'une cartographie incomplète.

Bonnes pratiques

• Limitez le LIMIT à la valeur nécessaire : des requêtes trop larges peuvent être lentes sur de grands référentiels.
• Utilisez OUTPUT graph uniquement lorsque les relations sont déclarées dans WITH ; un graphe sans relations ne sera composé que de nœuds isolés.
• Vérifiez les noms de champs dans la référence API — une faute de frappe dans un champ n'affiche simplement rien, sans message d'erreur.
• Avec EXISTS, déclarez la relation dans WITH uniquement si vous avez besoin d'afficher ses champs dans FIELDS ; sinon, EXISTS seul suffit à filtrer sans surcharge.
• Sauvegardez les requêtes récurrentes pour faciliter le travail en équipe et garantir la reproductibilité des cartographies.