# Écrire des requêtes

Utilisez Sigma pour composer des requêtes personnalisées au format SQL ANSI standard.

Toute personne de votre compte [autorisée à consulter des rapports](https://support.stripe.com/questions/can-i-invite-other-team-members-or-my-developer-to-use-my-stripe-account) peut utiliser l’[éditeur de requêtes Sigma](https://dashboard.stripe.com/sigma/queries) pour créer de nouvelles requêtes ou modifier des requêtes existantes. Notre assistant de requête basé sur un modèle de langage étendu (LLM) peut même vous aider à générer le langage SQL dont vous avez besoin à partir d’une invite en langage naturel.

## Interroger des ressources

La fenêtre de navigation située à gauche de l’éditeur propose un ensemble d’outils pour vous aider à rédiger votre requête. Y figurent :

- Vos requêtes précédemment enregistrées.
- Requêtes enregistrées par votre équipe.
- Schéma de table permettant de rechercher des sources de données.
- Modèles de requêtes Stripe.

### Requêtes et modèles enregistrés

La section **Rapports > Enregistrés** affiche les listes de requêtes précédemment enregistrées par vous et votre équipe. La section **Modèles** fournit des exemples de requêtes représentant les indicateurs et rapports les plus courants. Sélectionner un modèle ou une requête enregistrés permet de les charger dans l’éditeur de requête, où vous pourrez cliquer sur **Exécuter** pour les relancer et afficher les résultats.

Pour utiliser une requête enregistrée comme point de départ pour votre propre rapport personnalisé, cliquez sur son menu déroulant (⋯) et choisissez **Faire une copie**, ou chargez-la dans l’éditeur et cliquez sur **Faire une copie**. Cela vous permet de modifier le contenu dans l’éditeur et d’[enregistrer](https://docs.stripe.com/stripe-data/write-queries.md#saving-queries) vos modifications dans une nouvelle requête.

## Créer une requête

Lorsque vous ouvrez l’éditeur de requêtes, vous pouvez :

- Écrire en SQL ANSI standard directement dans l’éditeur.
- Choisissez une requête existante parmi vos requêtes précédemment enregistrées ou les modèles de Stripe et modifiez-la dans l’éditeur pour affiner les données renvoyées.

La requête suivante utilise le tableau `balance_transactions` pour obtenir des informations sur les cinq opérations sur solde les plus récentes liées à des remboursements :

```sql
select
  date_format(created, '%Y-%m-%d') as day,
  id,
  amount,
  currency,
  source_id
from balance_transactions
where type = 'refund'
order by day desc
limit 5
```

Cliquez sur **Exécuter** pour exécuter la requête et afficher les résultats dans un tableau situé en dessous de l’éditeur. Pour les requêtes plus complexes, l’exécution et l’affichage des résultats peuvent prendre davantage de temps. Toute tentative d’exécution d’une requête non valide génère un message d’erreur contenant le numéro de ligne et la position de l’erreur.

Les résultats de notre exemple de requête renvoient cinq lignes, correspondant chacune à un poste d’opération sur solde particulier, ainsi que les informations demandées à son sujet.

| jour       | id                  | montant     | devise | source_id          |
| ---------- | ------------------- | ----------- | ------ | ------------------ |
| 05/05/2026 | txn_orWziM4j7CiRL8J | -1 000 | USD    | re_orWziM4j7CiRL8J |
| 05/05/2026 | txn_orWziM4j7CiRL8J | -1 000 | USD    | re_orWziM4j7CiRL8J |
| 05/05/2026 | txn_orWziM4j7CiRL8J | -1 000 | USD    | re_orWziM4j7CiRL8J |
| 05/05/2026 | txn_orWziM4j7CiRL8J | -1 000 | EUR    | re_orWziM4j7CiRL8J |
| 05/05/2026 | txn_orWziM4j7CiRL8J | -1 000 | USD    | re_orWziM4j7CiRL8J |

### Joindre des tableaux

Vous pouvez joindre des colonnes de type **Clé principale** ou **Clé étrangère** à des colonnes similaires d’autres tables :

- **Clé principale** : représente l’identifiant unique (ID) de chaque enregistrement d’une table.
- **Clé étrangère** : représente des données qui font référence à la clé principale d’une autre table.

Par exemple, vous pouvez joindre la colonne `charge_id` de la table `disputes` (une clé étrangère) à la colonne `id` de la table `charges` (une clé principale).
![](https://b.stripecdn.com/docs-statics-srv/assets/disputes.f293434123d316ff4fafe2524e9b2b0d.png)

La jointure de tables vous permet d’obtenir des résultats plus complets dans vos jeux de données. Par exemple, vous pouvez modifier notre exemple d’opération sur solde pour l’associer à la table `refunds` afin d’obtenir des informations supplémentaires.

```sql
select
  date_format(date_trunc('day', balance_transactions.created), '%Y-%m-%d') as day,
  balance_transactions.amount,
  balance_transactions.currency,
  balance_transactions.source_id,
  refunds.charge_id
from
  balance_transactions
inner join refunds -- Joining these tables to retrieve additional information
on balance_transactions.source_id=refunds.id
where balance_transactions.type = 'refund'
order by day desc
limit 5
```

Cette requête étendue renvoie à présent l’ID du paiement initial correspondant au remboursement.

| jour       | montant     | devise | source_id          | charge.id          |
| ---------- | ----------- | ------ | ------------------ | ------------------ |
| 05/05/2026 | -1 000 | USD    | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |
| 05/05/2026 | -1 000 | USD    | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |
| 05/05/2026 | -1 000 | USD    | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |
| 05/05/2026 | -1 000 | EUR    | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |
| 05/05/2026 | -1 000 | USD    | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |

## Utiliser l’assistant

L’éditeur de requêtes de Stripe intègre un assistant LLM qui génère des résultats en langage SQL ANSI standard à partir d’une invite en langage naturel. L’éditeur peut exécuter les modes suivants :

- **Générer** utilise la question de l’invite pour écrire une nouvelle requête, en remplaçant toute requête SQL déjà chargée dans la fenêtre de l’éditeur.
- Le mode **Modifier** utilise la question de l’invite pour modifier le code SQL dans l’éditeur de requêtes.

> #### Vérifier votre mode
> 
> Pour obtenir la suggestion la plus précise possible, veillez à sélectionner le mode approprié pour votre invite. Lorsque l’éditeur contient du contenu, le mode passe automatiquement à **Modifier**. Si vous décidez ensuite de lancer une nouvelle requête sans changer de mode, la suggestion qui en résulte risque d’être limitée de manière inattendue en fonction de ce qui se trouve déjà dans l’éditeur.

### Envoyer des invites à l’assistant

1. Ouvrez l’[éditeur de requêtes Sigma](https://dashboard.stripe.com/sigma/queries) dans le Dashboard.

1. Sélectionnez le mode **Générer** et saisissez une question dans le champ prévu à cet effet. L’assistant :

   - Charge la suggestion de requête dans l’éditeur.
   - Affiche un récapitulatif de la suggestion.
   - Exécute la requête suggérée et renvoie les résultats sous forme de tableau en dessous de l’éditeur.
   - Passe en mode **Modifier** pour que vous puissiez affiner la requête en posant une question supplémentaire.

1. Continuez à interroger l’assistant et à visualiser les données obtenues jusqu’à ce que vous obteniez les informations souhaitées.

La capture d’écran suivante montre une instruction ayant généré le même code SQL que l’exemple de requête présenté au début de ce document :
![Donne des exemples d'invites à envoyer à l'assistant et les résultats obtenus.](https://b.stripecdn.com/docs-statics-srv/assets/sigma-assistant.5f0ca3dae331a32c4c58cf6ceecdbf65.png)

Voici des exemples de questions supplémentaires visant à modifier les suggestions :

- Trier ces résultats par montant.
- N’incluez pas les colonnes automatic_transfer ou reporting_category.
- Puis-je connaître le client pour chaque transaction ?

> #### Demander explicitement des données Connect
> 
> Lorsque vous demandez des données relatives à vos comptes connectés, mentionnez explicitement les comptes connectés dans votre requête. Par exemple : *Combien de nouveaux abonnements ont été générés par les comptes connectés le mois dernier ?*

### Afficher l’historique de chat

Sigma enregistre toutes les interactions entre vous et l’assistant dans l’historique de chat pour cette requête. Cliquez sur le bouton :history: en haut à droite de l’éditeur pour ouvrir le curseur de l’historique de chat.

Dans l’historique de chat, vous pouvez voir chaque invite donnée à l’assistant pour toute la durée de la requête (et pas seulement pour la session en cours) et la réponse de l’assistant. Cliquez sur **Afficher le SQL** pour afficher la suggestion SQL associée à une invite. Lorsqu’elle est ouverte, cliquez sur **Afficher dans l’éditeur** pour recharger cette suggestion dans la fenêtre principale de l’éditeur.

### Limites

- L’assistant de l’éditeur de requêtes ne répond qu’aux questions posées en anglais.
- L’assistant de l’éditeur de requêtes ne répond qu’aux questions relatives au schéma Stripe. Il ne peut pas répondre à des questions d’ordre général, telles que *Quelle est la couleur du logo de Stripe ?* ou *Quel temps fait-il aujourd’hui à San Francisco ?*

### Laisser un commentaire

Aidez-nous à améliorer l’assistant en répondant à l’invite **Cette réponse vous a-t-elle été utile ?** située entre l’éditeur et le tableau des résultats :

1. Cliquez sur **Oui** ou sur **Non**.

1. Détaillez précisément votre expérience d’utilisation de l’assistant ainsi que les améliorations que nous pouvons y apporter. Tous les avis sont les bienvenus, qu’il s’agisse de la précision de la suggestion, de l’interface utilisateur ou de tout autre aspect de votre expérience d’utilisation de l’assistant.

### Consentement aux données d’entraînement

En utilisant l’assistant Sigma, vous acceptez que Stripe enregistre et utilise vos entrées de chat pour l’entraîner et améliorer ses capacités. Si vous ne souhaitez pas que vos entrées de chat soient utilisées à cette fin, vous pouvez désactiver cette option dans vos [paramètres](https://dashboard.stripe.com/settings/sigma).

## Visualiser et télécharger les résultats de la recherche

Vous pouvez [planifier vos requêtes](https://docs.stripe.com/stripe-data/schedule-queries.md) pour qu’elles s’exécutent sur une base quotidienne, hebdomadaire ou mensuelle. Nous vous envoyons les résultats par e-mail ou sous la forme d’un événement *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests).

Les résultats de la recherche s’affichent dans un tableau en dessous de l’éditeur. Vous pouvez :

- Afficher un maximum de 1 000 résultats.
- Trier les résultats en cliquant sur les en-têtes des colonnes.
- Redimensionnez chaque colonne pour faciliter la lecture des résultats.

Vous pouvez également créer un graphique pour les requêtes comportant moins de 10 000 résultats. Vous pouvez :

- Créer des graphiques linéaires ou à barres avec des axes y et x personnalisés.
- Regrouper par colonne de tableau

Lorsque vous enregistrez un graphique dans une requête, celui-ci s’affiche avec les paramètres que vous avez choisis à chaque fois que vous effectuez la requête. Seul l’auteur de la requête peut modifier les graphiques.

Les montants sont exprimés dans la plus petite unité de la devise disponible, par exemple en cents pour l’USD ou en yens pour le JPY. Par exemple, un montant de `1 000` avec la devise `usd` correspond à 10 USD.

Cliquez sur **Télécharger le fichier CSV** pour exportez vos résultats afin de les exploiter dans des tableurs ou d’autres outils de reporting. Le fichier CSV téléchargé contient l’intégralité des résultats de la requête, de sorte que vous n’êtes pas limité aux 1 000 résultats affichables.

## Exécuter des requêtes à partir de l’API (Private preview)

Vous pouvez enregistrer des requêtes et les exécuter de manière programmatique dans votre propre environnement grâce à l’API Sigma.

## Enregistrer les requêtes

Après avoir exécuté une requête, cliquez sur **Enregistrer**. Stripe génère automatiquement un titre modifiable pour votre requête.

### Partager des requêtes

Les requêtes que vous enregistrez sont ajoutées sous **Rapports > Enregistrés** et mises à la disposition de tous les membres de l’équipe de votre compte. Chaque requête enregistrée se voit attribuer une URL unique, que vous pouvez partager en cliquant sur **Partager**. Vous pouvez utiliser ce lien comme raccourci pour un rapport que vous utilisez régulièrement, ou le partager directement avec les autres membres de l’équipe sur votre compte Stripe.

Vous ne pouvez partager des requêtes qu’avec les membres de votre équipe. Les requêtes partagées ne sont accessibles qu’en lecture seule, ce qui signifie que les autres membres de votre équipe ne peuvent pas modifier celles que vous créez. Si un membre souhaite apporter des modifications à votre requête, il peut en enregistrer une copie et la modifier.