Langage de requête Kantree (KQL)

Rechercher parmi les cartes

Pour rechercher parmi les titres des cartes, utilisez juste les mots-clé que vous avez en tête. Il y a 3 mots-clé que vous ne pouvez pas utiliser directement, parce qu’ils sont réservé par le système de recherche: and, or, not. Si vous voulez quand même les utiliser dans votre recherche, vous pouvez les entourer de guillemets (ie. oranges "and" berries).

Pour chercher des cartes qui ne correspondent pas au mots-clé, ajoutez le mot-clé not devant votre recherche (ie. not oranges). Si vous avez besoin d’exclure les cartes correspondant à une phrase, entourez les mots-clé de guillemets (eg. not "oranges berries").

Pour chercher une carte avec une référence spécifique, utilisez # suivi de la référence (eg. #123).

Pour chercher une carte qui est dans un groupe, utilisez # suivi par le nom du groupe. Si le nom du groupe contient des espaces, ignorez-les (ie. pour cherche les cartes dans le groupe “Liste 2”, utilisez #liste2).

Pour chercher une carte qui a un membre du projet dans au moins un de ses attributs, utilisez @ suivi du nom d’utilisateur (eg. @username). Vous pouvez utilisez @me pour cherchez vos propres cartes.

Les noms d'utilisateur et les groupes peuvent contenir des . et des espaces. Pour utiliser des mots avec ces caractères, entourez-les d'accolades @{user name} et #{List 2}).

Attributs

Vous pouvez chercher des cartes à partir de leurs attributs en utilisant l’un des deux syntaxes suivantes: attribut=valeur ou {attribut}=valeur. La première ne peut seulement être utilisée avec des noms d’attribut sans caractères spéciaux et sans espaces. Sinon utilisez la dernière (eg. {attribut avec espace}=valeur).

Les opérateurs disponibles sont :

  • =: égal à (eg. {Contact} = "john@doe.com")
  • !=: différent de (eg. {Nombre d'heures estimé} != 10)
  • > ou >=: supérieur à et supérieur ou égal à (eg. {Nombre d'heures estimé} > 10)
  • < ou <=: inférieur à et inférieur ou égal à (eg. {Nombre d'heures estimé} <= 10)
  • ~=: à peu près égal à (pour des valeurs textuelles). (eg. description ~= orange)

Si l’attribut est une liste de valeur (comme les attributs de type membres), utilisez l’opérateur in : @username in Assignés.

Quand on compare des attributs, les valeurs peuvent être :

  • une valeur vide (qui veut dire que la carte n’a pas de valeur pour cet attribut): empty (eg. trouver toutes les cartes sans description: description=empty)
  • un nombre: 10 ou 12.1 ou -3.4
  • une chaine de caractères: mot ou "plusieurs mots entourés par des guillemets"
  • yes ou no (pour les attributs oui/non)
  • une date: une chaine de caractères entourée de guillemets utilisant le format: YYYY-MM-DD (eg. "2017-02-05"). Quelques mots-clé spéciaux peuvent être utilisés en tant que date: today, tomorrow, yesterday. (eg. {due date}<today)
  • un membre: @username
  • une référence de carte: #123
  • une référence d’object (voir plus bas)

Vous pouvez aussi utiliser des expressions arithmétiques (ie. 3 + 4).

Plusieurs attributs spéciaux existent :

  • ref: référence de carte (eg. ref=123)
  • title: titre de carte (eg. title="ma tâche")
  • created at: la date de cration de la carte (eg. {created at}="2017-02-01")
  • created by: l’utilsateur qui a créé la carte (eg. {created by}=@me)
  • state: l’état de la carte (eg. state=completed)
  • started_at: la dernière date à laquelle la carte est passé dans l’état en cours.
  • finished at: la dernière date à laquelle la carte est passée dans l’un des états suivants, abandonné, terminé or fermé
  • resolution_time: le temps écoulé entre finished_at et started_at
  • archived: si la carte a été archivé (valeur oui/non: archived=yes)
  • parent: titre de la carte parent
  • nb children: nombre de carte enfants
  • model: nom du modèle (eg. model=bug)
  • project: nom du projet (eg. project="My Project")
  • organization: nom de l’organisation

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

Combiner des conditions

Vous pouvez utiliser plusieurs conditions dans vos requêtes. Vous n’avez qu’à les mettre les unes à la suite des autres. Toutes les conditions doivent être remplies pour qu’une carte puisse correspondre.

Pour des requêtes plus flexible, vous pouvez combiner des conditions en utilisant les opérateurs logiques :

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

Si aucun opérateur logique n’est utilisé, and is used. Vous pouvez regroupez des conditions entre parenthèses. and a la priorité sur or.

Utilisation avancée

Fonctions

Ils existent 2 types de fonctions :

  • fonctions qui retournent une valeur (eg. now())
  • fonctions utilisées comme une condition (eg. date?("week"))

Fonctions disponibles :

  • now(): retourne la date du jour
  • ago(intervalle): retourne now() - intervalle. intervalle est une chaine de caractère contenant un nombre suivi d’une unité - en anglais (days, weeks, months, years, …)
  • period(intervalle): retourne une periode de temps à ajouter à une date existante, par exemple now() + period("1 week")

Exemple: trouver les cartes qui avaient une échéance il y a 3 jours: {échéance} = ago("3 days")

Les fonctions conditionnelles disponibles :

  • is_in_active_group?(): vérifie si la carte est dans un group qui a des dates de début et de fin et si aujourd’hui est entre ces dates.
  • is_in_group?(nom_groupe, nom_type): vérifie si la carte est dans le groupe nom_groupe (nom_type optionnel).
  • was_in_group?(nom_groupe, nom_type): verifie si la carte a été dans le groupe nom_groupe (nom_type optionnel).
  • is_in_group_type?(nom_type): vérifie si la carte est dans le type de groupe nom_type.
  • date?(date): vérifie si au moins un attribut de type date de la carte correspond a la date spécifiée entre parenthèse. Exemple de formats valides de date : “27-05-2018”, “week”, “month”, “year”, “week+1” (pour la semaine prochaine), “week-1” (pour la semaine dernière), “week-2” (pour la semaine avant la dernière)

Références d’object

Les références d’object peuvent être utilisées pour retirer des valeurs d’une carte ou d’un utilisateur. Elles peuvent être utilisées dans des expressions arithmériques ou dans des comparaisons d’attributs.

Pour obtenir une valeur d’attribut d’un carte, utilisez la syntaxe suivante : {#ref:attribut} (eg. {#123:Nombre d'heures estimé}).

Pour obtenir une valeur d’un attribut d’utilisateur, utilisez la syntaxe suivante : {@username:attribute} (eg. {@me:email}). Les attributs suivants sont disponibles pour les utilisateurs : email, username.

Exemples

Trouvez les cartes qui me sont assignées (en utilisant l’attribut Assignés) :

@me in assignés

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

@me in assignés #backlog

Trouvez toutes les cartes qui arrivent à échéance demain (en utilisant l’attribut Echéance) :

{échéance}=tomorrow

Trouvez toutes les cartes qui ont le mot “problème” dans leur description (en utilisant l’attribut Description) :

description ~= problème

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

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

Trouvez toutes les cartes dont l’échéance est dépassée et qui n’ont pas d’assignés :

assignés=empty {échéance}<today

Trouvez toutes les cartes qui sont vieilles de plus de 3 jours et qui n’ont pas de description :

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

Trouvez toutes les cartes qui ont le modèle Bug et qui sont vieilles de plus de 1 semaine :

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