Langage de requête Kantree (KQL)

Kantree a un langage de requête puissant qui vous permet de filtrer ou de chercher des cartes, et aussi de calculer des valeurs à partir d’elles.

Voici le plan de ce guide. Cliquez sur la section dont vous avez besoin pour tirer le meilleur de KQL :

1. Où l’utiliser
2. Filtrer les cartes
3. Le champ formule
4. Faire référence aux champs
5. Combiner des conditions
6. Usage avancé
7. La différence entre les champs KQL et les variables
8. Exemples

Où utiliser KQL

KQL (Kantree Query Language) est le langage de requête de Kantree. Vous l’utilisez pour :

• filtrer les cartes d’une vue : cliquez sur Filtrer, puis sur l’onglet KQL. L’onglet Filtre construit pour vous des filtres simples, et l’onglet Demander écrit le filtre à partir d’une phrase, si l’assistant est activé dans votre organisation.

  

  L’éditeur KQL colore votre requête et vous suggère les champs et les valeurs pendant que vous tapez.

• chercher dans tous vos workspaces : cliquez sur la loupe dans la barre latérale de l’application, tapez votre recherche, puis appuyez sur Entrée.

  

• calculer des valeurs dans les dashboards, sur un ou plusieurs workspaces. Voir Dashboards.
• calculer des valeurs dans une carte, avec un champ formule.
• définir des conditions et des valeurs dans les automatisations. Voir Automatisations.

Filtrer les cartes

KQL utilise des mots-clés en anglais. Vous pouvez chercher du texte ou n’importe quelle valeur des champs de vos cartes. Certains champs spéciaux existent dans toutes les cartes (voir plus bas).

Pour les filtres courants, utilisez l’onglet Filtre du menu de filtre. Quand il ne suffit pas, utilisez l’onglet KQL.

Les différents types de filtres

Les filtres de texte

Pour chercher dans les titres des cartes, tapez les mots.

Pour trouver les cartes qui ne contiennent pas un mot, ajoutez not devant : not oranges. Pour exclure une expression, mettez-la entre guillemets droits : not "oranges fraises".

Les filtres par référence de carte

Pour trouver une carte par sa référence, tapez # suivi du numéro, par exemple #123.

Les filtres par groupe et par libellé

Pour trouver les cartes d’un groupe (un état, un libellé, une valeur d’un champ sélection…), tapez # suivi du nom du groupe, sans espaces. Par exemple, pour les cartes dans « En revue » : #enrevue.

Les filtres par membre

Pour trouver les cartes où un membre apparaît dans un champ de membres, tapez @ suivi du nom d’utilisateur, par exemple @utilisateur. Utilisez @me pour vos propres cartes.

Les noms avec des points ou des espaces

Quand un nom d’utilisateur, un groupe ou un libellé contient . ou des espaces, mettez-le entre accolades : @{nom utilisateur}, #{En revue}.

Le champ formule

Le champ formule est un type de champ de carte qui vous permet d’écrire une formule KQL pour calculer une valeur automatiquement.

Dans ce champ, vous pouvez utiliser :

• des références à des champs, par exemple {Montant} ou {Date de livraison}
• des fonctions KQL, par exemple as_number(), as_date(), today() ou period()
• les opérateurs arithmétiques +, -, / et *

Exemple simple : 3 + 4

Astuce : quand vous réutilisez le résultat d'un champ formule dans une autre formule, faites attention aux types. Par défaut, le résultat d'un champ formule est en général interprété comme du texte.

Utilisez as_number() pour refaire un calcul numérique, ou as_date() pour réutiliser une date calculée.

Exemple : as_number({formule #1}) * as_number({formule #2})

Faire référence aux champs

Dans vos filtres et vos formules KQL, vous pouvez faire référence aux champs des cartes avec l’une de ces syntaxes : champ=valeur ou {champ}=valeur. La première forme ne fonctionne que si le nom du champ n’a pas d’espaces ni de caractères spéciaux.

Les opérateurs disponibles sont :

• = : égal à (par ex. {Contact} = "jean@exemple.com")
• != : différent de (par ex. {Heures estimées} != 10)
• > ou >= : supérieur à, et supérieur ou égal à (par ex. {Heures estimées} > 10)
• < ou <= : inférieur à, et inférieur ou égal à (par ex. {Heures estimées} <= 10)
• ~= : correspondance approximative pour les textes (par ex. description ~= orange)

Quand vous comparez des champs, les valeurs peuvent être :

• une valeur vide, qui signifie que le champ n’est pas rempli : empty (par ex. description=empty)
• un nombre : 10, 12.1 ou -3.4
• un texte : mot ou "plusieurs mots entre guillemets droits"
• yes ou no pour les champs oui/non
• une date : un texte entre guillemets droits au format AAAA-MM-JJ (par ex. "2017-02-05"). Quelques mots-clés spéciaux peuvent aussi servir de dates : today, tomorrow, yesterday (par ex. {Date d'échéance}<today)
• un membre : @utilisateur
• une référence de carte : #123
• une référence d’objet (voir plus bas)

Les champs KQL spéciaux

Voici la liste des champs spéciaux disponibles dans toutes vos formules et tous vos filtres KQL :

• ref : la référence de la carte (par ex. ref=123)
• title : le titre de la carte (par ex. title="ma tâche")

• created at : la date de création de la carte (exemple de filtre : {created at}="2025-02-01")

  Vous pouvez aussi utiliser ce champ pour afficher une valeur sur votre carte.

  Pour réutiliser cette valeur dans un autre champ formule, par exemple pour calculer une nouvelle date, utilisez as_date() : le résultat d’un champ formule est du texte par défaut.

  Exemple : as_date({Date de livraison} + period("2 days"))

• created by : l’utilisateur qui a créé la carte (par ex. {created by}=@me)
• updated at : la date de la dernière modification

• state : l’état de la carte (par ex. state=completed) et quelques alias

  state fait référence aux états internes de Kantree, que vous avez peut-être associés aux étapes de votre workflow.

  • state=todo : correspond à undecided, accepted ou waiting
  • state=doing : correspond à in_progress
  • state=done : correspond à completed
  • state=finished : correspond à completed, closed ou dropped
• started at : la dernière date à laquelle la carte est passée dans l’état in progress
• finished at : la dernière date à laquelle la carte est passée dans l’un de ces états : dropped, completed ou closed
• resolution time : le temps écoulé entre started at et finished at
• archived : si la carte est archivée (valeur oui/non : archived=yes)
• archived at : la date d’archivage (par ex. {archived at}>="2025-01-03")
• parent : l’id de la carte parent (utilisable dans des requêtes comme {parent} in {champ relation #1} ou {parent}=#14)
• hlevel : le niveau de la carte dans la hiérarchie du workspace. Par exemple, une sous-carte renvoie 2 ; pour filtrer les sous-cartes : hlevel=2
• nb children : le nombre de sous-cartes
• nb comments : le nombre de commentaires
• last comment at : la date du dernier commentaire
• last comment by : l’auteur du dernier commentaire (par ex. {last comment by}=@me)
• model ou type : le nom du type de carte (par ex. type=bug)
• workspace ou project : le nom du workspace (par ex. workspace="Mon workspace")
• org ou organization : le nom de l’organisation
• team : le nom de l’équipe
• form : le nom du formulaire (si la carte a été créée par un formulaire)
• form submitted by : {form submitted by}=@utilisateur, ou {form submitted by}="email" si la personne qui a envoyé le formulaire n’a pas de compte Kantree
• shared : si la carte a un lien de partage public

Vous pouvez utiliser le mot-clé not devant chacune de ces conditions pour chercher les cartes qui ne leur correspondent pas, par exemple not @me in assignés.

Combiner des conditions

Vous pouvez utiliser plusieurs conditions dans la même requête en les plaçant les unes après les autres. Une carte doit remplir toutes les conditions pour correspondre.

Pour des requêtes plus souples, combinez les conditions avec des opérateurs logiques :

• and : toutes les conditions doivent être remplies
• or : au moins une condition doit être remplie

Pour créer une règle d’exclusion, utilisez l’éditeur KQL avec l’une de ces formes :

• and not
• or not

Par exemple, les cartes avec le libellé « Offre commerciale » qui ne sont pas assignées à Flora :

#{Offre commerciale} and not @flora in assignés

Usage avancé

Les fonctions

Il existe 3 sortes de fonctions :

• les fonctions qui renvoient une valeur (par ex. now())
• les fonctions d’agrégation, qui calculent des statistiques sur un ensemble de valeurs (par ex. avg())
• les fonctions utilisées comme conditions (par ex. date?("week"))

Les fonctions qui renvoient une valeur

• now() : renvoie la date et l’heure actuelles
• today() : renvoie la date du jour, sans l’heure
• period(intervalle) : renvoie un intervalle utilisable dans des calculs de dates, par exemple now() + period("1 week"). La valeur est suivie d’une unité de temps en anglais : year, month, week, day ou hour.

• ago(intervalle) : renvoie la date obtenue en retirant l’intervalle à la date actuelle

  Exemple : trouver les cartes dont la date d’échéance était il y a 3 jours ou plus : {Date d'échéance} <= ago("3 days")

• ahead(intervalle) : renvoie la date obtenue en ajoutant l’intervalle à la date actuelle

  Exemple : trouver les cartes dont la date d’échéance est dans 3 jours : {Date d'échéance} = ahead("3 days")

• week_start([date]) : renvoie le premier jour de la semaine de la date donnée. Sans paramètre, la semaine actuelle est utilisée.
• week_end([date]) : renvoie le dernier jour de la semaine de la date donnée. Sans paramètre, la semaine actuelle est utilisée.
• workweek_start([date]) : renvoie le premier jour ouvré de la semaine de la date donnée. Sans paramètre, la semaine actuelle est utilisée.
• workweek_end([date]) : renvoie le dernier jour ouvré de la semaine de la date donnée. Sans paramètre, la semaine actuelle est utilisée.
• week_number([date]) : renvoie le numéro de la semaine
• month_start([date]) : renvoie le premier jour du mois de la date donnée. Sans paramètre, le mois actuel est utilisé.
• month_end([date]) : renvoie le dernier jour du mois de la date donnée. Sans paramètre, le mois actuel est utilisé.
• month_number([date]) : renvoie le numéro du mois
• year_start([date]) : renvoie le premier jour de l’année de la date donnée. Sans paramètre, l’année actuelle est utilisée.
• year_end([date]) : renvoie le dernier jour de l’année de la date donnée. Sans paramètre, l’année actuelle est utilisée.
• year([date]) : renvoie l’année
• count_days([début], [fin]) : renvoie le nombre de jours entre début et fin. Sans paramètre, renvoie le nombre de jours du mois actuel.
• count_working_days([début], [fin]) : renvoie le nombre de jours ouvrés entre début et fin. Sans paramètre, renvoie le nombre de jours ouvrés du mois actuel.
• last_moved_in_group_at(nom_du_groupe, [nom_du_type]) : renvoie la date à laquelle la carte est entrée pour la dernière fois dans le groupe donné (nom_du_type est facultatif et sert à distinguer un champ en double dans le workspace)
• if(expression, valeur, valeurSinon) : renvoie valeur si expression est vraie, et valeurSinon si expression est fausse
• as_string(valeur) : convertit une valeur en texte, par exemple as_string({Points})
• as_date(valeur) : convertit une valeur en date, par exemple as_date({Champ texte})

• as_daterange({date 1}, {date 2}) : convertit deux champs date en une plage de dates

  

• date:start : la date de début d’un champ date qui contient une plage, par exemple {date #2:start}
• date:end : la date de fin d’un champ date qui contient une plage, par exemple {date #2:end}
• as_number(valeur) : convertit une valeur en nombre, par exemple as_number({Champ texte})
• size(liste) : renvoie le nombre d’éléments d’une liste, par exemple size({assignés})
• first(valeur) : renvoie la première valeur choisie dans un champ qui contient une liste de valeurs, comme Libellés
• substring(texte, début, nombre) : renvoie une partie d’un texte, par exemple substring("hello world", 6, 5) = "world"
• concat(valeur1, valeur2, ...) : met plusieurs valeurs bout à bout
• round(valeur, [décimales]) : arrondit un nombre au nombre de décimales choisi (par défaut, renvoie un entier)

• card(titre_du_workspace, ref_de_la_carte) : renvoie l’id d’une carte d’un autre workspace

  Exemple : dans une automatisation avec l’action Remplir un champ à partir d’une formule, vous pouvez relier une carte d’un autre workspace avec un champ relation : card("Nom du workspace", ${card:Nom du champ relation à remplir avec l'id})

Les fonctions d’agrégation

• max() : renvoie la valeur la plus haute. Exemple : dans une vue Dashboard, afficher la plus grande valeur d’un champ nombre.

• min() : renvoie la valeur la plus basse. Exemple : dans une vue Dashboard, afficher la plus petite valeur d’un champ date, c’est-à-dire la date la plus ancienne.

  Vous pouvez aussi utiliser min() ou max() avec les dates des états des cartes.

  Exemples :

  max({updated at})
  min({created at})
  max({started at})
  min({finished at})
  

  Exemple pour filtrer les cartes terminées avec la modification la plus récente :

  query(state=done, max({updated at}))
  

• avg() : renvoie la moyenne
• sum() : renvoie une somme
• sum_logs(nom_de_catégorie, nom_du_champ, [utilisateur], [date_début], [date_fin]) : renvoie la somme des valeurs d’un champ des logs de la catégorie donnée. Elle peut être limitée à un utilisateur et/ou à une période. Pour les champs de type Temps, le résultat est en secondes.
• count() : renvoie un nombre d’éléments
• count_logs(nom_de_catégorie, [utilisateur], [date_début], [date_fin]) : renvoie le nombre de logs d’une catégorie. Il peut être limité à un utilisateur et/ou à une période.

Les fonctions de condition

• full_text_search?(texte) : vérifie si le titre de la carte ou une valeur d’un de ses champs contient ce texte
• is_in_group_type?(nom_du_type) : vérifie si la carte appartient au type de groupe donné (nom_du_type est facultatif et sert à distinguer un champ en double dans le workspace)
• is_in_active_group?() : vérifie si la carte est dans un groupe qui a des dates de début et de fin, et si aujourd’hui est dans cette période
• is_in_group?(nom_du_groupe, nom_du_type) : vérifie si la carte est dans le groupe nom_du_groupe (nom_du_type est facultatif et sert à distinguer un champ en double dans le workspace)
• was_in_group?(nom_du_groupe, nom_du_type) : vérifie si la carte a déjà été dans nom_du_groupe (nom_du_type est facultatif et sert à distinguer un champ en double dans le workspace)
• date?(date) : vérifie si au moins un champ date de la carte correspond à la date donnée. Exemples de formats valides : "05-27-2018" (MM-JJ-AAAA), "week", "month", "year", "week+1" pour la semaine prochaine, "week-1" pour la semaine dernière, "week-2" pour la semaine d’avant
• contains_member?(@utilisateur) : vérifie si un champ de membres de la carte contient @utilisateur
• is_pii?(identifiant) : vérifie si au moins un champ marqué comme données personnelles a une valeur et, si un identifiant est donné (@utilisateur ou un texte), si au moins un de ces champs le contient
• is_subscribed?() : vérifie si vous êtes abonné à la carte
• parent?(expression_kql) : vérifie si au moins un parent de la carte correspond à l’expression KQL donnée
• children?(expression_kql) : vérifie si au moins une sous-carte directe correspond à l’expression KQL donnée
• descendants?(expression_kql) : vérifie si au moins une carte descendante correspond à l’expression KQL donnée

• relationships?(expression_kql) : vérifie si au moins une carte d’un champ relation correspond à l’expression KQL donnée

  Exemple : relationships?(title="Carte 10") trouve les cartes qui ont un champ relation avec un lien vers Carte 10.

  Si vous avez plusieurs champs relation, vous pouvez indiquer le champ dans lequel chercher :

  relationships?(title="Carte 2", {nom du champ relation})

Les références d’objets

Les références d’objets servent à récupérer une valeur d’une carte ou d’un utilisateur. Elles peuvent être utilisées dans des calculs ou dans des comparaisons de champs.

Pour obtenir la valeur d’un champ d’une carte, utilisez cette syntaxe : {#ref:champ} (par ex. {#123:Heures estimées}).

Pour obtenir la valeur d’un champ d’un utilisateur, utilisez cette syntaxe : {@utilisateur:champ} (par ex. {@me:email}). Les champs disponibles pour les utilisateurs sont : email, username.

Les variables

La différence entre les champs KQL et les variables

Les champs KQL
Ils servent à filtrer vos vues, à créer des conditions pour déclencher des automatisations, à filtrer les requêtes des automatisations, à écrire les requêtes des vues Dashboard, ou à calculer des valeurs dans un champ formule.

Leur forme : {champ}

Voir la liste des champs KQL spéciaux plus haut.

Les variables
Elles ne servent que dans les automatisations.

Leur forme : ${variable}, ${card:variable} ou ${parent:card:variable}

Dans les automatisations, vous pouvez combiner des champs KQL et des variables, mais l’inverse n’est pas possible.

Les variables suivantes ne peuvent être utilisées que dans une automatisation, dans :

• les filtres des conditions
• les filtres des requêtes (balayer les cartes)
• publier un commentaire
• envoyer un e-mail
• remplir un champ à partir d’une formule
• définir une variable

Ces variables peuvent être combinées avec les champs KQL spéciaux, pour travailler sur d’autres cartes, et pas seulement sur celle qui est en cours de traitement (la carte qui a déclenché l’action).

Exemple : filtrer les cartes en comparant deux champs nombre.

as_number(${parent:card:attr_number}) >= {attr_number}

Vous pouvez par exemple agir sur un ensemble de cartes tout en récupérant des informations d’autres cartes.

• Nom de l’organisation
  ${organization}

• Nom de l’équipe
  ${team}

• Nom du workspace
  ${workspace:title}

• URL du workspace
  ${workspace:url}

• Nom de l’utilisateur qui a déclenché l’action
  ${author}

• ID de la carte
  ${card:id}

• Référence de la carte (#ref)
  ${card:ref}

• URL de la carte
  ${card:url}

• URL de partage de la carte
  ${card:share_url}

• Titre de la carte
  ${card:title}

• URL de la demande de la carte
  ${card:request_url}

• Champ de la carte
  ${card:nom du champ}

• Liste des sous-cartes
  ${children}

• Contenu du commentaire
  ${comment:message}

  Ne fonctionne qu’avec le déclencheur un nouveau commentaire est posté.

  Exemple : reprendre le contenu du commentaire publié dans une action d’envoi d’e-mail, ou pour publier un commentaire sur une autre carte.

• Nom d’utilisateur de l’auteur du commentaire
  ${comment:username}

Avec l’action Définir une variable, vous pouvez créer votre propre variable et la réutiliser dans une règle d’automatisation.

Exemples

Trouver les cartes qui me sont assignées (avec le champ Assignés) :

@me in assignés

Trouver les cartes qui me sont assignées dans le groupe Backlog :

@me in assignés #backlog

Trouver toutes les cartes qui arrivent à échéance demain (avec le champ Date d’échéance) :

{Date d'échéance}=tomorrow

Trouver toutes les cartes qui contiennent le mot problème dans leur description :

description ~= problème

Trouver toutes les cartes qui me sont assignées ou que j’ai créées :

@me in assignés or {created by}=@me

Trouver toutes les cartes en retard sans assignés :

assignés=empty {Date d'échéance}<today

Trouver toutes les cartes de plus de 3 jours sans description :

description=empty {created at} > ago("3 days")

Trouver toutes les cartes du type Bug de plus d’une semaine :

type=bug {created at} > ago("1 week")

Exemples avec des dates

Afficher des dates dans une carte

Le champ date

Ajoutez un champ de type Date et personnalisez son titre et ses options. Par défaut, il contient une seule date, mais vous pouvez autoriser la sélection d’une plage de dates.

Le champ formule - Les états des cartes Kantree

Utilisez un champ formule et ajoutez l’une des expressions suivantes :

• Date de création : {created at}
• Date de dernière modification : {updated at}
• Date d’archivage : {archived at}

Entourez l’expression de as_date() pour l’afficher au format AAAA-MM-JJ.

Les champs formule qui contiennent une date peuvent être utilisés dans les vues temporelles : Calendrier, Timeline et Gantt.

Le champ formule - Calculer une date automatiquement

Vous pouvez calculer une date automatiquement en ajoutant un champ formule et en utilisant la fonction period("").

À partir d’un autre champ, plus ou moins une période :

Je veux afficher une date de contrôle 7 jours avant la livraison (champ « Date de livraison »).

Je veux afficher une date de fin de garantie 1 an après la date de livraison (champ « Date de livraison »).

Le champ formule - Utiliser les dates de début et de fin

Si vous utilisez un champ date en mode plage de dates, le début de la plage correspond à {Nom du champ:start} et la fin à {Nom du champ:end}.

Pour extraire dans des champs séparés la date de début et la date de fin d’un champ date en mode plage, utilisez des champs formule avec {Nom du champ:start} et {Nom du champ:end}.

À l’inverse, si vous avez des champs séparés pour la date de début et la date de fin et que vous voulez en faire une plage de dates, utilisez un champ formule avec as_daterange().

Je veux créer un champ date avec une plage qui commence à la date de création de ma carte et qui finit à la date de livraison.

Filtrer les cartes sur une date ou entre deux dates

Le champ date

L’assistant montre les opérateurs disponibles, comme Est après et Est avant, et vous permet de choisir la période dans le calendrier.

Pour chercher entre deux dates, ajoutez un opérateur and.

Le champ formule

Contrairement à un champ date, quand vous filtrez sur un champ formule qui affiche une date, vous devez taper la date vous-même dans l’assistant.

La date s’écrit au format AAAA-MM-JJ.

Pour filtrer entre deux dates, passez dans l’éditeur KQL et utilisez les opérateurs >, < et =.

Pour chercher les cartes créées entre le 2025-03-01 et le 2025-03-08, utilisez ces opérateurs. Pour inclure les deux dates, utilisez >= ou <=.

Filtrer les cartes sur une date plus ou moins une période

Vous pouvez utiliser ahead() pour ajouter une période et ago() pour en retirer une, avec des expressions comme "X days", "X months" ou "X years".

Pour filtrer les cartes dont la date d’échéance est à J+10 :

Pour filtrer les cartes dont la date d’échéance est à J-1 an :

Pour filtrer les cartes dont la date d’échéance est à J-1 an et après :

Compter entre deux champs qui contiennent une date ou une charge de travail

Vous pouvez compter les jours entre deux dates, qu’elles viennent d’un champ date ou d’un champ formule.

Utilisez un champ formule avec count_days() ou count_working_days().

Je veux compter le nombre de jours ouvrés entre le début de ma tâche et sa date de contrôle.

Je veux compter le nombre de jours pour passer d’un groupe à un autre, quand le groupe représente le statut.

Utiliser une date comme condition

La condition de déclenchement d’une automatisation

Vous pouvez utiliser une date comme condition pour déclencher une automatisation.

Je veux qu’un commentaire soit publié sur la carte quand la « Date de livraison » est après la « Date d’échéance ».

L’action de l’automatisation, la publication d’un commentaire :

Créer un indicateur visuel

Utilisez un champ formule avec une fonction if(), ou une automatisation avec l’action Remplir un champ à partir d’une formule.

Vous pouvez aussi faire ce type d’action avec des automatisations.

Par rapport à un champ formule, une automatisation vous permet de choisir quand le champ est rempli, et de combiner plusieurs actions, comme remplir un champ date et un champ texte.

Remplir un champ date selon une condition

Vous pouvez utiliser la fonction if() pour remplir un champ date selon une condition.

Quand la date de livraison est après la date d’échéance, je veux que le champ où je crée la formule, « Date d’échéance réelle », soit rempli avec la date d’échéance initiale plus 14 jours. Sinon, je veux que « Date d’échéance réelle » affiche la date d’échéance initiale, sans changement.

if({Date de livraison}>{Date d'échéance},as_date({Date d'échéance réelle}+period("14 days")),as_date({Date d'échéance}))