Contactez-nous

Documentation : MatchQL

MatchQL

MatchQL (Match Query Language) est la syntaxe JSON pour requêter les API Pertinence.

Structure d'une requête

Voici la structure globale d'une requête MatchQL :

{
	"return": {
		"fields": [...],
		"from": ...,
		"size": ...,
		"compatibility_for": {
			"field": "...",
			"values": [...]
		},
		"sort": [
			{
				"field": "...",
				"order": "..."
			},
			...
		]
	},
	"criteria": [
		{
			"field": "...",
			"priority_weight": "...",
			"priority_order": "...",
			"clause": [
				{
					"operator": "...",
					"expression": ...
				},
				...
			]
		},
		...
	]
}
Propriété Type Commentaire
return object Objet qui spécifie ce que l'on souhaite en retour de l'API
return.fields array Liste des champs (avec leur valeur) que l'on souhaite récupérer dans les documents matchés.
Le nombre de champs est limité à 20 au maximum
return.from integer Offset du premier résultat à retourner. Démarrer à 0
return.size integer Nombre de résultats à retourner depuis l'offset from.
Le nombre de résultats est limité à 1000 au maximum.

Attention : plus les résultats à retourner seront nombreux, plus votre applicatif sera lent. Nous conseillons de limiter à moins de 50 résultats retournés puis d'utiliser ensuite la pagination
compatibility_for object À spécifier uniquement pour l'API Compatibility. Indique sur quels documents on va calculer une compatibilité
compatibility_for.field string Nom du champ qui servira à récupérer les documents pour lesquels il faut calculer une compatibilité. Le champ doit être de type double ou keyword

Conseil : nous conseillons de mettre un identifiant (id) unique. Il est donc nécessaire que vos données aient été indexées au préalable avec un champ qui correspond à un identifiant unique
compatibility_for.values array Liste des valeurs du champ qui sert à récupérer les documents
sort array Tableau spécifiant l'ordonnancement des résultats.

Note : l'ordonnancement par défaut des résultats est le scoring dont le nom du champ (field) est "_score"
sort[n].field string Nom du champ d'ordonnancement. Le champ doit être de type double, keyword ou date
sort[n].order string Ordre d'ordonnancement. Peut valoir asc ou desc
criteria array Tableau d'objets qui spécifie les critères de la requête.

Chaque objet du tableau est relié par un OU logique.

Par défaut, le moteur Pertinence va essayer de trouver les documents qui satisfont tous les critères.
Mais si ce n'est pas possible, il va trouver les documents qui satisfont au mieux la plupart des critères, en fonction de la pondération et de la priorité
criteria[n].field string Nom de champ
criteria[n].priority_weight string Pondération du critère.

Peut valoir default (valeur par défaut spécifiée lors de la configuration du moteur), mandatory, necessary, important ou optional
criteria[n].priority_order string Priorité du critère parmi les autres critères de même pondération.

Peut valoir default (valeur par défaut spécifiée lors de la configuration du moteur) ou un nombre entier positif
clause array Liste d'objets représentant les opérations à appliquer sur le champ.

Chaque objet du tableau est relié par un ET logique
clause[n].operator string Opérateur de la clause. La liste des opérateurs disponibles par type de champ est explicitée dans la section qui suit
clause[n].expression various Expression de la clause. La liste des expressions disponibles par type de champ et opérateur est explicitée dans la section qui suit

Clauses par type de champ

Liste des clauses (operator / expression) possibles selon chaque type de champ

⬪ boolean
operator expression Exemple
equal

Égal à...

 true ou false 
...
"clause": [
	...
	{
		"operator": "equal",
		"expression": true
	}
	...
]
...
not_equal

Différent de...

 true ou false 
...
"clause": [
	...
	{
		"operator": "not_equal",
		"expression": false
	}
	...
]
...
⬪ double
operator expression Exemple
equal

Égal à...

 Nombre réel 
...
"clause": [
	...
	{
		"operator": "equal",
		"expression": 59
	}
	...
]
...
not_equal

Différent de...

 Nombre réel 
...
"clause": [
	...
	{
		"operator": "not_equal",
		"expression": -128.667498
	}
	...
]
...
greater_than

Strictement supérieur à...

 Nombre réel 
...
"clause": [
	...
	{
		"operator": "greater_than",
		"expression": 1200
	}
	...
]
...
less_than

Strictement inférieur à...

 Nombre réel 
...
"clause": [
	...
	{
		"operator": "less_than",
		"expression": 0
	}
	...
]
...
greater_than_or_equal

Supérieur ou égal à...

 Nombre réel 
...
"clause": [
	...
	{
		"operator": "greater_than_or_equal",
		"expression": -500.90
	}
	...
]
...
less_than_or_equal

Inférieur ou égal à...

 Nombre réel 
...
"clause": [
	...
	{
		"operator": "less_than_or_equal",
		"expression": 620490
	}
	...
]
...
include

Spécifie une clause où le champ vaut au moins une des valeurs de l'expression. Équivalant du IN (...) en SQL

 Tableau de nombres réels 
...
"clause": [
	...
	{
		"operator": "include",
		"expression": [12, 55, 95.5, -200, -48.9]
	}
	...
]
...
exclude

Spécifie une clause où le champ est différent de toutes les valeurs de l'expression. Équivalant du NOT IN (...) en SQL

 Tableau de nombres réels 
...
"clause": [
	...
	{
		"operator": "exclude",
		"expression": [1200, -5.4]
	}
	...
]
...
⬪ keyword
operator expression Exemple
equal

Égal à...

 Chaîne de caractères 
...
"clause": [
	...
	{
		"operator": "equal",
		"expression": "rouge"
	}
	...
]
...
not_equal

Différent de...

 Chaîne de caractères 
...
"clause": [
	...
	{
		"operator": "not_equal",
		"expression": "orange"
	}
	...
]
...
include

Spécifie une clause où le champ vaut au moins une des valeurs de l'expression. Équivalant du IN (...) en SQL

 Tableau de chaîne de caractères 
...
"clause": [
	...
	{
		"operator": "include",
		"expression": ["bleu", "jaune", "vert"]
	}
	...
]
...
exclude

Spécifie une clause où le champ est différent de toutes les valeurs de l'expression. Équivalant du NOT IN (...) en SQL

 Tableau de chaîne de caractères 
...
"clause": [
	...
	{
		"operator": "exclude",
		"expression": ["rouge", "orange"]
	}
	...
]
...
⬪ text
operator expression Exemple
match

Spécifie une clause où le champ correspond le mieux au texte de l'expression

 Texte 
...
"clause": [
	...
	{
		"operator": "match",
		"expression": "voiture bleue"
	}
	...
]
...
not_match

Spécifie une clause où le champ ne contient pas le texte de l'expression

 Texte 
...
"clause": [
	...
	{
		"operator": "not_match",
		"expression": "voiture rouge"
	}
	...
]
...
include

Spécifie une clause où le champ vaut au moins une des valeurs de l'expression. Équivalant du IN (...) en SQL

 Tableau de chaîne de textes 
...
"clause": [
	...
	{
		"operator": "include",
		"expression": ["voiture bleue", "voiture jaune"]
	}
	...
]
...
exclude

Spécifie une clause où le champ est différent de toutes les valeurs de l'expression. Équivalant du NOT IN (...) en SQL

 Tableau de chaîne de textes 
...
"clause": [
	...
	{
		"operator": "exclude",
		"expression": ["toit ouvrant", "climatisation"]
	}
	...
]
...
⬪ date
operator expression Exemple
equal

Égal à...

 Date UTC 
...
"clause": [
	...
	{
		"operator": "equal",
		"expression": "2020-04-08"
	}
	...
]
...
not_equal

Différent de...

 Date UTC 
...
"clause": [
	...
	{
		"operator": "not_equal",
		"expression": "2019-01"
	}
	...
]
...
greater_than

Strictement supérieur à...

 Date UTC 
...
"clause": [
	...
	{
		"operator": "greater_than",
		"expression": "2020-04-08T10:53:52.478592Z"
	}
	...
]
...
less_than

Strictement inférieur à...

 Date UTC 
...
"clause": [
	...
	{
		"operator": "less_than",
		"expression": "2015"
	}
	...
]
...
greater_than_or_equal

Supérieur ou égal à...

 Date UTC 
...
"clause": [
	...
	{
		"operator": "greater_than_or_equal",
		"expression": "2019-12-25"
	}
	...
]
...
less_than_or_equal

Inférieur ou égal à...

 Date UTC 
...
"clause": [
	...
	{
		"operator": "less_than_or_equal",
		"expression": "2020-05-25T19:00:00"
	}
	...
]
...
include

Spécifie une clause où le champ vaut au moins une des valeurs de l'expression. Équivalant du IN (...) en SQL

 Date UTC 
...
"clause": [
	...
	{
		"operator": "include",
		"expression": ["2014-01-24", "2016"]
	}
	...
]
...
exclude

Spécifie une clause où le champ est différent de toutes les valeurs de l'expression. Équivalant du NOT IN (...) en SQL

 Date UTC 
...
"clause": [
	...
	{
		"operator": "exclude",
		"expression": ["2020-01-24", "2020-01-23"]
	}
	...
]
...
⬪ geo_point
operator expression Exemple
boxed_in

Spécifie une clause où le champ est géométriquement contenu dans le rectangle spécifié par l'expression.

- top_left définit le point géographique supérieur gauche au format GeoJSON

- bottom_right définit le point géographique inférieur droit au format GeoJSON

Objet JSON 
...
"clause": [
	...
	{
		"operator": "boxed_in",
		"expression": {
			"top_left": {
				"type": "Point",
				"coordinates": [2.411849, 48.812851]
			},
			"bottom_right": {
				"type": "Point",
				"coordinates": [2.443392,48.801376]
			}
		}
	}
	...
]
...
polygoned_in

Spécifie une clause où le champ est géométriquement contenu dans le polygone spécifié par l'expression.

- polygon définit le polygone au format GeoJSON

Objet JSON 
...
"clause": [
	...
	{
		"operator": "polygoned_in",
		"expression": {
			"polygon": {
				"type": "Polygon",
				"coordinates": [
					[
						[5.75814,45.88408],
						[5.72427,45.89457],
						[5.70509,45.89703], 
						[5.75814,45.88408]
					]
				]
			}
		}
	}
	...
]
...
multipolygoned_in

Spécifie une clause où le champ est géométriquement contenu dans le multipolygone spécifié par l'expression.

- multipolygon définit le multipolygone au format GeoJSON

Objet JSON 
...
"clause": [
	...
	{
		"operator": "multipolygoned_in",
		"expression": {
			"multipolygon": {
				"type": "MultiPolygon",
				"coordinates": [
					[[
						[5.75814,45.88408],
						[5.72427,45.89457],
						[5.70509,45.89703], 
						[5.75814,45.88408]
					]],
					[[
						[5.70379,45.87889],
						[5.71254,45.86766],
						[5.73932,45.87423],
						[5.70379,45.87889]
					]]
				]
			}
		}
	}
	...
]
...
circled_in

Spécifie une clause où le champ est géométriquement contenu dans le cercle spécifié par l'expression.

- point définit le centre du cercle au format GeoJSON

- distance est un nombre réel positif qui définit le rayon du cercle

- unit est l'unité pour distance :
km (kilomètre)
m (mètre)
cm (centimètre)
mm (millimètre)
mi (mile)
yd (yard)
ft (feet)
in (inch)
nmi (nautic mile)

Objet JSON 
...
"clause": [
	...
	{
		"operator": "circled_in",
		"expression": {
			"point": {
				"type": "Point",
				"coordinates": [2.411849, 48.812851]
			},
			"distance": 15.2,
			"unit": "km"
		}
	}
	...
]
...
⬪ geo_shape

operator expression Exemple
intersect

Spécifie une clause où le champ a une intersection géometrique avec la forme spécifiée par l'expression.

- shape définit la forme géometrique au format GeoJSON. Tous les types GeoJSON sont possibles (Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon).

 Objet JSON 
...
"clause": [
	...
	{
		"operator": "intersect",
		"expression": {
			"shape": {
				"type": "LineString",
				"coordinates": [
					[5.75814,45.88408],
					[5.72427,45.89457],
					[5.70509,45.89703]
				]
			}
		}
	}
	...
]
...
contain

Spécifie une clause où le champ contient géométriquement la forme spécifiée par l'expression.

- shape définit la forme géometrique au format GeoJSON. Tous les types GeoJSON sont possibles (Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon).

 Objet JSON 
...
"clause": [
	...
	{
		"operator": "contain",
		"expression": {
			"shape": {
				"type": "Polygon",
				"coordinates": [
					[
						[5.75814,45.88408],
						[5.72427,45.89457],
						[5.70509,45.89703], 
						[5.75814,45.88408]
					]
				]
			}
		}
	}
	...
]
...

Exemples

Exemples complets de requêtes avec la syntaxe MatchQL, qui se basent sur l'index de la démo en ligne pour l'immobilier 

{
	"return": {
		"fields": ["id", "title_formatted", "city_name", "city_postal_code", "listing_type", "property_type", "price", "updated_date"],
		"from": 0,
		"size": 20,
		"sort": [{
				"field": "updated_date",
				"order": "desc"
			},
			{
				"field": "_score",
				"order": "asc"
			},
			{
				"field": "id",
				"order": "asc"
			}
		]
	},
	"criteria": [{
			"field": "terrasse",
			"priority_weight": "important",
			"priority_order": "default",
			"clause": [{
				"operator": "equal",
				"expression": true
			}]
		},
		{
			"field": "price",
			"priority_weight": "default",
			"priority_order": "default",
			"clause": [{
				"operator": "greater_than_or_equal",
				"expression": 300000
			}, {
				"operator": "less_than_or_equal",
				"expression": 500000
			}]
		},
		{
			"field": "property_type",
			"priority_weight": "necessary",
			"priority_order": 1,
			"clause": [{
				"operator": "include",
				"expression": ["house", "flat"]
			}, {
				"operator": "exclude",
				"expression": ["parking"]
			}]
		},
		{
			"field": "region_name",
			"priority_weight": "default",
			"priority_order": "default",
			"clause": [{
				"operator": "match",
				"expression": "France"
			}]
		},
		{
			"field": "updated_date",
			"priority_weight": "optional",
			"priority_order": "default",
			"clause": [{
				"operator": "greater_than_or_equal",
				"expression": "2016"
			}, {
				"operator": "less_than_or_equal",
				"expression": "2020-01-01"
			}]
		},
		{
			"field": "geometry",
			"priority_weight": "mandatory",
			"priority_order": 2,
			"clause": [{
				"operator": "circled_in",
				"expression": {
					"point": {
						"type": "Point",
						"coordinates": [2.344847, 48.850861]
					},
					"distance": 20,
					"unit": "km"
				}
			}]
		}
	]
}

✎ Éditer ou exécuter cette requête en ligne : https://reqbin.com/c-ktrn2gn4

Exemple pour l'API Compatibility

{
	"return": {
		"fields": ["id", "city_name", "city_postal_code", "listing_type", "property_type", "price"],
		"from": 0,
		"size": 20,
		"compatibility_for": {
			"field": "id",
			"values": [28853,28854]
		},
		"sort": [{
				"field": "updated_date",
				"order": "desc"
			},
			{
				"field": "id",
				"order": "asc"
			}
		]
	},
	"criteria": [{
			"field": "alarme",
			"priority_weight": "default",
			"priority_order": "default",
			"clause": [{
				"operator": "equal",
				"expression": true
			}]
		},
		{
			"field": "transport_transport",
			"priority_weight": "default",
			"priority_order": "default",
			"clause": [{
				"operator": "greater_than_or_equal",
				"expression": 4
			}, {
				"operator": "less_than_or_equal",
				"expression": 5
			}]
		},
		{
			"field": "listing_type",
			"priority_weight": "default",
			"priority_order": "default",
			"clause": [{
				"operator": "include",
				"expression": ["buy"]
			}]
		},
		{
			"field": "region_name",
			"priority_weight": "default",
			"priority_order": "default",
			"clause": [{
				"operator": "match",
				"expression": "France"
			}]
		},
		{
			"field": "updated_date",
			"priority_weight": "default",
			"priority_order": "default",
			"clause": [{
				"operator": "greater_than_or_equal",
				"expression": "2016"
			}]
		},
		{
			"field": "geometry",
			"priority_weight": "default",
			"priority_order": "default",
			"clause": [{
				"operator": "circled_in",
				"expression": {
					"point": {
						"type": "Point",
						"coordinates": [2.344847, 48.850861]
					},
					"distance": 20,
					"unit": "km"
				}
			}]
		}
	]
}

✎ Éditer ou exécuter cette requête en ligne : https://reqbin.com/c-bymkowyt

Contactez-nous

Vous souhaitez implémenter du Matching ou du Scoring sur votre site ou votre application ? Nous sommes à votre écoute pour vous accompagner.
Réponse rapide !

Contactez-nous