--- title: "Champs de modèles spécifiques à PostgreSQL" version: 2.2 locale: fr source: https://docs.djangoproject.com/fr/2.2/ref/contrib/postgres/fields/ canonical: https://djangodocs.dev/fr/2.2/ref/contrib/postgres/fields/ --- # Champs de modèles spécifiques à PostgreSQL Tous ces champs sont disponibles dans le module `django.contrib.postgres.fields`. ## Indexation de ces champs [`Index`](/fr/2.2/ref/models/indexes/#django.db.models.Index) et [`Field.db_index`](/fr/2.2/ref/models/fields/#django.db.models.Field.db_index) créent les deux un index B-tree, ce qui n’est pas spécialement utile lors de requêtes sur des types de données complexes. Les index tels que [`GinIndex`](/fr/2.2/ref/contrib/postgres/indexes/#django.contrib.postgres.indexes.GinIndex) et [`GistIndex`](/fr/2.2/ref/contrib/postgres/indexes/#django.contrib.postgres.indexes.GistIndex) sont mieux adaptés, même si le choix de l’index dépend des requêtes effectivement utilisées. En général, GiST est un bon choix pour les [champs d’intervalle](#range-fields) et le champ [`HStoreField`](#django.contrib.postgres.fields.HStoreField), alors que GIN est souvent utile pour les champs [`ArrayField`](#django.contrib.postgres.fields.ArrayField) et [`JSONField`](#django.contrib.postgres.fields.JSONField). ## `ArrayField` #### `class ArrayField(base_field, size=None, **options)` Un champ pour stocker des listes de données. La plupart des types de champs peuvent être utilisés ; il suffit de passer une autre instance de champ dans l’attribut [`base_field`](#django.contrib.postgres.fields.ArrayField.base_field). Vous pouvez aussi indiquer une taille dans [`size`](#django.contrib.postgres.fields.ArrayField.size). `ArrayField` peut être imbriqué pour stocker des tableaux multidimensionnels. Si vous donnez une valeur [`default`](/fr/2.2/ref/models/fields/#django.db.models.Field.default) à ce champ, assurez-vous que ce soit un objet exécutable tel que `list` (pour une valeur par défaut vide) ou un objet exécutable qui renvoie une liste (par exemple une fonction). L’utilisation de `default=[]` n’est pas correct car cela crée une valeur par défaut mutante qui est partagée entre les instances de `ArrayField`. #### `base_field` Ce paramètre est obligatoire. Définit le type de données sous-jacent et le comportement du tableau. Il devrait s’agir d’une instance d’une sous-classe de [`Field`](/fr/2.2/ref/models/fields/#django.db.models.Field). Par exemple, cela pourrait être un [`IntegerField`](/fr/2.2/ref/models/fields/#django.db.models.IntegerField) ou un [`CharField`](/fr/2.2/ref/models/fields/#django.db.models.CharField). La plupart des types de champs sont autorisés, à l’exception de ceux qui gèrent des données relationnelles ([`ForeignKey`](/fr/2.2/ref/models/fields/#django.db.models.ForeignKey), [`OneToOneField`](/fr/2.2/ref/models/fields/#django.db.models.OneToOneField) et [`ManyToManyField`](/fr/2.2/ref/models/fields/#django.db.models.ManyToManyField)). Il est possible d’imbriquer des champs tabulaires, c’est-à-dire que `base_field` peut contenir une instance de `ArrayField`. Par exemple : ``` from django.contrib.postgres.fields import ArrayField from django.db import models class ChessBoard(models.Model): board = ArrayField( ArrayField( models.CharField(max_length=10, blank=True), size=8, ), size=8, ) ``` La transformation de valeurs entre la base de données et le modèle, la validation de données et la configuration ainsi que la sérialisation sont tous délégués au champ de base sous-jacent. #### `size` Ce paramètre est facultatif. Si présent, le tableau aura la taille maximale indiquée. Cette valeur est transmise à la base de données, même si PostgreSQL n’applique actuellement pas cette restriction. > **Note** > > Lors de l’imbrication de champs `ArrayField`, que le paramètre `size` soit défini ou non, PostgreSQL exige que les tableaux soient rectangulaires : > > ``` > from django.contrib.postgres.fields import ArrayField > from django.db import models > > class Board(models.Model): > pieces = ArrayField(ArrayField(models.IntegerField())) > > # Valid > Board(pieces=[ > [2, 3], > [2, 1], > ]) > > # Not valid > Board(pieces=[ > [2, 3], > [2], > ]) > ``` > > Si des formes irrégulières sont nécessaires, le sous-champ doit pouvoir être nul et les valeurs doivent être complétées avec `None`. ### Interrogation de `ArrayField` Il existe plusieurs recherches et transformations spécifiques au champ [`ArrayField`](#django.contrib.postgres.fields.ArrayField). Nous allons utiliser le modèle d’exemple suivant : ``` from django.contrib.postgres.fields import ArrayField from django.db import models class Post(models.Model): name = models.CharField(max_length=200) tags = ArrayField(models.CharField(max_length=200), blank=True) def __str__(self): return self.name ``` #### `contains` La recherche [`contains`](/fr/2.2/ref/models/querysets/#std-fieldlookup-contains) est surchargée pour [`ArrayField`](#django.contrib.postgres.fields.ArrayField). Les objets renvoyés sont ceux pour qui les valeurs transmises forment un sous-ensemble des données. Elle utilise l’opérateur SQL `@>`. Par exemple : ``` >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) >>> Post.objects.create(name='Third post', tags=['tutorial', 'django']) >>> Post.objects.filter(tags__contains=['thoughts']) , ]> >>> Post.objects.filter(tags__contains=['django']) , ]> >>> Post.objects.filter(tags__contains=['django', 'thoughts']) ]> ``` #### `contained_by` Il s’agit de l’inverse de la recherche [`contains`](#std-fieldlookup-arrayfield.contains), les objets renvoyés sont ceux pour qui les données forment un sous-ensemble des valeurs transmises. Elle utilise l’opérateur SQL `<@`. Par exemple : ``` >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) >>> Post.objects.create(name='Third post', tags=['tutorial', 'django']) >>> Post.objects.filter(tags__contained_by=['thoughts', 'django']) , ]> >>> Post.objects.filter(tags__contained_by=['thoughts', 'django', 'tutorial']) , , ]> ``` #### `overlap` Renvoie les objets dont les données contiennent au moins une valeur en commun avec celles transmises. Utilise l’opérateur SQL `&&`. Par exemple : ``` >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) >>> Post.objects.create(name='Third post', tags=['tutorial', 'django']) >>> Post.objects.filter(tags__overlap=['thoughts']) , ]> >>> Post.objects.filter(tags__overlap=['thoughts', 'tutorial']) , , ]> ``` #### `len` Renvoie la longueur du tableau. Les recherches disponibles à la suite de celle-ci sont celles qui sont disponibles pour les champs [`IntegerField`](/fr/2.2/ref/models/fields/#django.db.models.IntegerField). Par exemple : ``` >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) >>> Post.objects.filter(tags__len=1) ]> ``` #### Transformations d’indice Les transformations d’index indicent dans les tableaux. Tout nombre entier non négatif est utilisable. Aucune erreur n’est produite si l’indice dépasse la taille [`size`](#django.contrib.postgres.fields.ArrayField.size) du tableau. Les recherches disponibles à la suite de la transformation sont celles du champ [`base_field`](#django.contrib.postgres.fields.ArrayField.base_field). Par exemple : ``` >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) >>> Post.objects.filter(tags__0='thoughts') , ]> >>> Post.objects.filter(tags__1__iexact='Django') ]> >>> Post.objects.filter(tags__276='javascript') ``` > **Note** > > PostgreSQL utilise l’indiçage à partir de 1 pour les champs de type tableau lors de l’écriture de SQL brut. Cependant, ces indices ainsi que ceux utilisés dans les [`segmentations`](#std-fieldlookup-arrayfield.slice) emploient des indices depuis 0 afin de rester cohérent avec Python. #### Transformations de segmentation Les transformations de segmentation segmentent dans les tableaux. Toute paire de nombres entiers non négatifs peut être utilisée, séparée par un seul soulignement. Les recherches disponibles après la transformation ne changent pas. Par exemple : ``` >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) >>> Post.objects.create(name='Third post', tags=['django', 'python', 'thoughts']) >>> Post.objects.filter(tags__0_1=['thoughts']) , ]> >>> Post.objects.filter(tags__0_2__contains=['thoughts']) , ]> ``` > **Note** > > PostgreSQL utilise l’indiçage à partir de 1 pour les champs de type tableau lors de l’écriture de SQL brut. Cependant, ces segmentations ainsi que celles utilisées dans les [`indices`](#std-fieldlookup-arrayfield.index) emploient des indices depuis 0 afin de rester cohérent avec Python. > **Indices et segmentations avec les tableaux multidimensionnels** > > Le comportement de PostgreSQL est plutôt ésotérique lorsqu’il s’agit d’indicer ou de segmenter des tableaux à plusieurs dimensions. L’emploi des indices pour atteindre une donnée imbriquée fonctionne dans tous les cas, mais la plupart des autres segmentations se comportent bizarrement au niveau de la base de données et ne peuvent pas être prises en charge de manière cohérente et logique par Django. ## Champs `CIText` #### `class CIText(**options)` Une classe mixin pour créer des champs texte insensibles à la casse soutenus par le type [citext](https://www.postgresql.org/docs/current/citext.html). Lisez les [conséquences au niveau des performances](https://www.postgresql.org/docs/current/citext.html#id-1.11.7.17.7) avant de l’utiliser. Pour utiliser `citext`, employez l’opération [`CITextExtension`](/fr/2.2/ref/contrib/postgres/operations/#django.contrib.postgres.operations.CITextExtension) afin de [configurer l’extension citext](/fr/2.2/ref/contrib/postgres/operations/#create-postgresql-extensions) dans PostgreSQL avant la première opération de migration `CreateModel`. Si vous utilisez un champ [`ArrayField`](#django.contrib.postgres.fields.ArrayField) de `CIText`, vous devez ajouter `'django.contrib.postgres'` dans votre réglage [`INSTALLED_APPS`](/fr/2.2/ref/settings/#std-setting-INSTALLED_APPS), sinon les valeurs de champs apparaîtront sous forme de chaînes comme `'{thoughts,django}'`. Plusieurs champs qui utilisent cette classe mixin sont fournis : #### `class CICharField(**options)` #### `class CIEmailField(**options)` #### `class CITextField(**options)` Ces champs héritent respectivement de [`CharField`](/fr/2.2/ref/models/fields/#django.db.models.CharField), [`EmailField`](/fr/2.2/ref/models/fields/#django.db.models.EmailField) et [`TextField`](/fr/2.2/ref/models/fields/#django.db.models.TextField). `max_length` ne sera pas vérifiée au niveau de la base de données car `citext` se comporte comme le type PostgreSQL `text`. ## `HStoreField` #### `class HStoreField(**options)` Un champ pour stocker des paires clé-valeur. Le type de données Python utilisé est un dictionnaire `dict`. Les clés doivent être des chaînes et les valeurs peuvent être soit des chaînes, soit la valeur nulle (`None` en Python). Pour utiliser ce champ, il faut : 1. Ajouter `'django.contrib.postgres'` à votre réglage [`INSTALLED_APPS`](/fr/2.2/ref/settings/#std-setting-INSTALLED_APPS). 2. [Configurer l’extension hstore](/fr/2.2/ref/contrib/postgres/operations/#create-postgresql-extensions) dans PostgreSQL. Vous verrez une erreur du genre `can't adapt type 'dict'` si vous omettez la première étape, ou `type "hstore" does not exist` si vous omettez la seconde. > **Note** > > Parfois, il est utile de pouvoir limiter les clés admises comme valides pour un champ donné. Cela peut se faire à l’aide de [`KeysValidator`](/fr/2.2/ref/contrib/postgres/validators/#django.contrib.postgres.validators.KeysValidator). ### Interrogation de `HStoreField` En plus de la possibilité d’interroger en fonction de la clé, il existe quelques recherches tout exprès pour les champs `HStoreField`. Nous allons utiliser le modèle d’exemple suivant : ``` from django.contrib.postgres.fields import HStoreField from django.db import models class Dog(models.Model): name = models.CharField(max_length=200) data = HStoreField() def __str__(self): return self.name ``` #### Recherches par clé Pour rechercher en fonction d’une clé donnée, il suffit d’utiliser cette clé comme nom de requête : ``` >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie'}) >>> Dog.objects.filter(data__breed='collie') ]> ``` Il est possible d’enchaîner d’autres recherches après une recherche par clé : ``` >>> Dog.objects.filter(data__breed__contains='l') , ]> ``` Si la clé avec laquelle vous souhaitez rechercher entre en conflit avec le nom d’une recherche existante, vous devez utiliser la recherche [`hstorefield.contains`](#std-fieldlookup-hstorefield.contains) à la place. > **Warning** > > Comme n’importe quelle chaîne peut être une clé d’une valeur `hstore`, toute recherche autre que celles mentionnées ci-dessous sera interprétée comme une recherche par clé. Aucune erreur n’est produite. Faites spécialement attention aux erreurs de frappe et vérifiez systématiquement que vos requêtes fonctionnent correctement. #### `contains` La recherche [`contains`](/fr/2.2/ref/models/querysets/#std-fieldlookup-contains) est surchargée pour [`HStoreField`](#django.contrib.postgres.fields.HStoreField). Les objets renvoyés sont ceux pour qui le dictionnaire de paires clé-valeur est totalement contenu dans le champ. Elle utilise l’opérateur SQL `@>`. Par exemple : ``` >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador', 'owner': 'Bob'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) >>> Dog.objects.create(name='Fred', data={}) >>> Dog.objects.filter(data__contains={'owner': 'Bob'}) , ]> >>> Dog.objects.filter(data__contains={'breed': 'collie'}) ]> ``` #### `contained_by` Il s’agit de l’inverse de la recherche [`contains`](#std-fieldlookup-hstorefield.contains), les objets renvoyés sont ceux pour qui les paires de clé-valeur forment un sous-ensemble des valeurs transmises. Elle utilise l’opérateur SQL `<@`. Par exemple : ``` >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador', 'owner': 'Bob'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) >>> Dog.objects.create(name='Fred', data={}) >>> Dog.objects.filter(data__contained_by={'breed': 'collie', 'owner': 'Bob'}) , ]> >>> Dog.objects.filter(data__contained_by={'breed': 'collie'}) ]> ``` #### `has_key` Renvoie les objets dont les données contiennent la clé indiquée. Utilise l’opérateur SQL `?`. Par exemple : ``` >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) >>> Dog.objects.filter(data__has_key='owner') ]> ``` #### `has_any_keys` Renvoie les objets dont les données contiennent au moins une des clés indiquées. Utilise l’opérateur SQL `?|`. Par exemple : ``` >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'owner': 'Bob'}) >>> Dog.objects.create(name='Fred', data={}) >>> Dog.objects.filter(data__has_any_keys=['owner', 'breed']) , ]> ``` #### `has_keys` Renvoie les objets dont les données contiennent toutes les clés indiquées. Utilise l’opérateur SQL `?&`. Par exemple : ``` >>> Dog.objects.create(name='Rufus', data={}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) >>> Dog.objects.filter(data__has_keys=['breed', 'owner']) ]> ``` #### `keys` Renvoie l’ensemble des clés des objets concernés. Notez que l’ordre n’est pas garanti, ce qui fait que cette transformation est surtout utile quand elle est combinée à des recherches sur [`ArrayField`](#django.contrib.postgres.fields.ArrayField). Utilise la fonction SQL `akeys()`. Par exemple : ``` >>> Dog.objects.create(name='Rufus', data={'toy': 'bone'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) >>> Dog.objects.filter(data__keys__overlap=['breed', 'toy']) , ]> ``` #### `values` Renvoie l’ensemble des valeurs des objets concernés. Notez que l’ordre n’est pas garanti, ce qui fait que cette transformation est surtout utile quand elle est combinée à des recherches sur [`ArrayField`](#django.contrib.postgres.fields.ArrayField). Utilise la fonction SQL `avalues()`. Par exemple : ``` >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) >>> Dog.objects.filter(data__values__contains=['collie']) ]> ``` ## `JSONField` #### `class JSONField(encoder=None, **options)` Un champ pour stocker des données JSON encodées. En Python, les données sont représentées dans leur format natif correspondant : dictionnaires, listes, chaînes, nombres, booléens et `None`. #### `encoder` Une classe facultative de codage en JSON pour sérialiser les types de données non prises en charge par le sérialiseur JSON standard (`datetime`, `uuid`, etc.). Par exemple, vous pouvez utiliser la classe [`DjangoJSONEncoder`](/fr/2.2/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder) ou toute autre classe héritant de [`json.JSONEncoder`](https://docs.python.org/3/library/json.html#json.JSONEncoder). Lorsque la valeur est récupérée de la base de données, elle sera dans le format choisi par le codeur personnalisé (la plupart du temps une chaîne), il vous faudra donc intervenir pour reconvertir la valeur dans le type de données initial ([`Model.from_db()`](/fr/2.2/ref/models/instances/#django.db.models.Model.from_db) et [`Field.from_db_value()`](/fr/2.2/ref/models/fields/#django.db.models.Field.from_db_value) sont deux points d’entrée possibles pour cela). La désérialisation pourrait devoir tenir compte de l’incertitude liée au type de la valeur d’entrée. Par exemple, vous courez le risque de renvoyer un objet `datetime` qui était en fait une chaîne qui était fortuitement au même format que celui choisi pour les objets `datetime`. Si vous donnez une valeur [`default`](/fr/2.2/ref/models/fields/#django.db.models.Field.default) à ce champ, assurez-vous que ce soit un objet exécutable tel que `dict` (pour une valeur par défaut vide) ou un objet exécutable qui renvoie un dictionnaire (par exemple une fonction). L’utilisation de `default={}` n’est pas correct car cela crée une valeur par défaut mutante qui est partagée entre les instances de `JSONField`. > **Note** > > PostgreSQL dispose de deux types de données natifs basés sur JSON : `json` et `jsonb`. La principale différence entre eux est la façon dont ils sont stockés et comment ils peuvent être interrogés. Le champ `json` de PostgreSQL est stocké comme la représentation textuelle d’origine du JSON et doit être décodé à la volée lorsqu’on l’interroge sur la base de clés. Le champ `jsonb` est stocké en fonction de la structure réelle du JSON qui permet l’indexation. En contre-partie, l’écriture du champ `jsonb` est légèrement plus coûteuse. `JSONField` utilise le type `jsonb`. ### Interrogation de `JSONField` Nous allons utiliser le modèle d’exemple suivant : ``` from django.contrib.postgres.fields import JSONField from django.db import models class Dog(models.Model): name = models.CharField(max_length=200) data = JSONField() def __str__(self): return self.name ``` #### Interrogations de clé, d’indice et de chemin Pour rechercher en fonction d’une clé de dictionnaire donnée, il suffit d’utiliser cette clé comme nom de requête : ``` >>> Dog.objects.create(name='Rufus', data={ ... 'breed': 'labrador', ... 'owner': { ... 'name': 'Bob', ... 'other_pets': [{ ... 'name': 'Fishy', ... }], ... }, ... }) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': None}) >>> Dog.objects.filter(data__breed='collie') ]> ``` Il est possible d’enchaîner plusieurs clés pour former une recherche de chemin : ``` >>> Dog.objects.filter(data__owner__name='Bob') ]> ``` Si la clé est un entier, elle sera interprétée comme une recherche d’indice de tableau : ``` >>> Dog.objects.filter(data__owner__other_pets__0__name='Fishy') ]> ``` Si la clé avec laquelle vous souhaitez rechercher entre en conflit avec le nom d’une recherche existante, utilisez la recherche [`jsonfield.contains`](#std-fieldlookup-jsonfield.contains) à la place. Si une seule clé ou indice est donnée, l’opérateur SQL `->` est utilisé. Si plusieurs opérateurs sont donnés, alors c’est l’opérateur `#>` qui est utilisé. Pour rechercher une valeur nulle dans des données JSON, utilisez `None` comme valeur ``` >>> Dog.objects.filter(data__owner=None) ]> ``` Pour rechercher des clés manquantes, utilisez l’expression de recherche `isnull`: ``` >>> Dog.objects.create(name='Shep', data={'breed': 'collie'}) >>> Dog.objects.filter(data__owner__isnull=True) ]> ``` > **Changed in Django 2.1** > > Dans les anciennes versions, l’emploi de `None` comme valeur de recherche trouvait des objets qui ne possédaient pas cette clé au lieu des objets qui possédaient cette clé contenant la valeur `None`. > **Warning** > > Comme n’importe quelle chaîne peut être une clé d’un objet JSON, toute recherche autre que celles mentionnées ci-dessous sera interprétée comme une recherche par clé. Aucune erreur n’est produite. Faites spécialement attention aux erreurs de frappe et vérifiez systématiquement que vos requêtes fonctionnent correctement. #### Opérations de contenance et de clé [`JSONField`](#django.contrib.postgres.fields.JSONField) partage les interrogations liées à la contenance et aux clés avec le champ [`HStoreField`](#django.contrib.postgres.fields.HStoreField). - [`contains`](#std-fieldlookup-hstorefield.contains) (accepte n’importe quel JSON et pas seulement un dictionnaire de chaînes) - [`contained_by`](#std-fieldlookup-hstorefield.contained_by) (accepte n’importe quel JSON et pas seulement un dictionnaire de chaînes) - [`has_key`](#std-fieldlookup-hstorefield.has_key) - [`has_any_keys`](#std-fieldlookup-hstorefield.has_any_keys) - [`has_keys`](#std-fieldlookup-hstorefield.has_keys) ## Champs d’intervalle Il existe cinq types de champs d’intervalle, correspondant au types d’intervalles natifs de PostgreSQL. Ces champs sont utilisés pour stocker un intervalle de valeurs ; par exemple, l’heure de début et de fin d’un événement ou l’intervalle des âges appropriés à une activité. Tous les champs d’intervalle produisent des objets [Range psycopg2](https://www.psycopg.org/docs/extras.html#adapt-range) en Python, mais acceptent aussi des tuples en entrée si aucune information de limite n’est nécessaire. Par défaut, la limite inférieure est incluse et la limite supérieure exclue ; c’est-à-dire `[)`. ### `IntegerRangeField` #### `class IntegerRangeField(**options)` Stocke un intervalle de nombres entiers. Basé sur un [`IntegerField`](/fr/2.2/ref/models/fields/#django.db.models.IntegerField). Représenté par un `int4range` dans la base de données et un [`NumericRange`](https://www.psycopg.org/docs/extras.html#psycopg2.extras.NumericRange) en Python. Quelles que soient les limites indiquées lors de l’enregistrement des données, PostgreSQL renvoie toujours un intervalle dans sa forme canonique qui inclut la limite inférieure et exclut la limite supérieure ; c’est-à-dire `[)`. ### `BigIntegerRangeField` #### `class BigIntegerRangeField(**options)` Stocke un intervalle de nombres entiers étendus. Basé sur un [`BigIntegerField`](/fr/2.2/ref/models/fields/#django.db.models.BigIntegerField). Représenté par un `int8range` dans la base de données et un [`NumericRange`](https://www.psycopg.org/docs/extras.html#psycopg2.extras.NumericRange) en Python. Quelles que soient les limites indiquées lors de l’enregistrement des données, PostgreSQL renvoie toujours un intervalle dans sa forme canonique qui inclut la limite inférieure et exclut la limite supérieure ; c’est-à-dire `[)`. ### `DecimalRangeField` #### `class DecimalRangeField(**options)` > **New in Django 2.2** Stocke un intervalle de valeurs en virgule flottante. Basé sur un [`DecimalField`](/fr/2.2/ref/models/fields/#django.db.models.DecimalField). Représenté par un `numrange` dans la base de données et un [`NumericRange`](https://www.psycopg.org/docs/extras.html#psycopg2.extras.NumericRange) en Python. ### `FloatRangeField` #### `class FloatRangeField(**options)` Stocke un intervalle de valeurs en virgule flottante. Basé sur un [`FloatField`](/fr/2.2/ref/models/fields/#django.db.models.FloatField). Représenté par un `numrange` dans la base de données et un [`NumericRange`](https://www.psycopg.org/docs/extras.html#psycopg2.extras.NumericRange) en Python. > **Deprecated since Django 2.2** > > Obsolète depuis la version 2.2: Utilisez plutôt [`DecimalRangeField`](#django.contrib.postgres.fields.DecimalRangeField). ### `DateTimeRangeField` #### `class DateTimeRangeField(**options)` Stocke un intervalle de date/heures. Basé sur la classe [`DateTimeField`](/fr/2.2/ref/models/fields/#django.db.models.DateTimeField). Représenté par un `tstzrange` dans la base de données et par un [`DateTimeTZRange`](https://www.psycopg.org/docs/extras.html#psycopg2.extras.DateTimeTZRange) dans Python. ### `DateRangeField` #### `class DateRangeField(**options)` Stocke un intervalle de dates. Basé sur un [`DateField`](/fr/2.2/ref/models/fields/#django.db.models.DateField). Représenté par un `daterange` dans la base de données et un [`DateRange`](https://www.psycopg.org/docs/extras.html#psycopg2.extras.DateRange) en Python. Quelles que soient les limites indiquées lors de l’enregistrement des données, PostgreSQL renvoie toujours un intervalle dans sa forme canonique qui inclut la limite inférieure et exclut la limite supérieure ; c’est-à-dire `[)`. ### Interrogation de champs d’intervalle Il existe un certain nombre de recherches et de transformations spécifiques aux champs d’intervalle. Ils sont disponibles pour tous les champs ci-dessus, mais nous allons utiliser le modèle d’exemple suivant : ``` from django.contrib.postgres.fields import IntegerRangeField from django.db import models class Event(models.Model): name = models.CharField(max_length=200) ages = IntegerRangeField() start = models.DateTimeField() def __str__(self): return self.name ``` Nous allons aussi utiliser les objets d’exemple suivants : ``` >>> import datetime >>> from django.utils import timezone >>> now = timezone.now() >>> Event.objects.create(name='Soft play', ages=(0, 10), start=now) >>> Event.objects.create(name='Pub trip', ages=(21, None), start=now - datetime.timedelta(days=1)) ``` et `NumericRange`: ``` >>> from psycopg2.extras import NumericRange ``` #### Fonctions de contenance Comme pour les autres champs PostgreSQL, trois opérateurs de contenance standard sont disponibles : `contains`, `contained_by` et `overlap`, utilisant respectivement les opérateurs SQL `@>`, `<@` et `&&`. ##### `contains` ``` >>> Event.objects.filter(ages__contains=NumericRange(4, 5)) ]> ``` ##### `contained_by` ``` >>> Event.objects.filter(ages__contained_by=NumericRange(0, 15)) ]> ``` La recherche `contained_by` est aussi disponible pour les types de champ autres que intervalle : [`IntegerField`](/fr/2.2/ref/models/fields/#django.db.models.IntegerField), [`BigIntegerField`](/fr/2.2/ref/models/fields/#django.db.models.BigIntegerField), [`FloatField`](/fr/2.2/ref/models/fields/#django.db.models.FloatField), [`DateField`](/fr/2.2/ref/models/fields/#django.db.models.DateField) et [`DateTimeField`](/fr/2.2/ref/models/fields/#django.db.models.DateTimeField). Par exemple : ``` >>> from psycopg2.extras import DateTimeTZRange >>> Event.objects.filter(start__contained_by=DateTimeTZRange( ... timezone.now() - datetime.timedelta(hours=1), ... timezone.now() + datetime.timedelta(hours=1), ... ) ]> ``` ##### `overlap` ``` >>> Event.objects.filter(ages__overlap=NumericRange(8, 12)) ]> ``` #### Fonctions de comparaison Les champs d’intervalle prennent en charge les recherches standard : [`lt`](/fr/2.2/ref/models/querysets/#std-fieldlookup-lt), [`gt`](/fr/2.2/ref/models/querysets/#std-fieldlookup-gt), [`lte`](/fr/2.2/ref/models/querysets/#std-fieldlookup-lte) et [`gte`](/fr/2.2/ref/models/querysets/#std-fieldlookup-gte). Elles ne sont pas particulièrement utiles, la comparaison s’opère d’abord sur la limite inférieure et si nécessaire, sur la limite supérieure ensuite. C’est également la stratégie adoptée pour trier selon un champ d’intervalle. Il est recommandé d’utiliser plutôt les opérateurs spécifiques de comparaison d’intervalle. ##### `fully_lt` Les intervalles renvoyés sont strictement inférieurs à l’intervalle transmis. En d’autres termes, tous les points d’un intervalle renvoyé sont plus petits que tous ceux de l’intervalle transmis. ``` >>> Event.objects.filter(ages__fully_lt=NumericRange(11, 15)) ]> ``` ##### `fully_gt` Les intervalles renvoyés sont strictement supérieurs à l’intervalle transmis. En d’autres termes, tous les points d’un intervalle renvoyé sont plus grands que tous ceux de l’intervalle transmis. ``` >>> Event.objects.filter(ages__fully_gt=NumericRange(11, 15)) ]> ``` ##### `not_lt` Les intervalles renvoyés ne contiennent aucun élément plus petit que ceux de l’intervalle transmis, c’est-à-dire que la limite inférieure d’un intervalle renvoyé est au moins égale à la limite inférieure de l’intervalle transmis. ``` >>> Event.objects.filter(ages__not_lt=NumericRange(0, 15)) , ]> ``` ##### `not_gt` Les intervalles renvoyés ne contiennent aucun élément plus grand que ceux de l’intervalle transmis, c’est-à-dire que la limite supérieure d’un intervalle renvoyé n’est pas plus grande que la limite supérieure de l’intervalle transmis. ``` >>> Event.objects.filter(ages__not_gt=NumericRange(3, 10)) ]> ``` ##### `adjacent_to` Les intervalles renvoyés partagent une limite avec l’intervalle transmis. ``` >>> Event.objects.filter(ages__adjacent_to=NumericRange(10, 21)) , ]> ``` #### Interrogation à l’aide des limites Trois transformations sont disponibles pour être utilisées dans les requêtes. Vous pouvez extraire la limite inférieure ou supérieure, ou interroger sur la base de l’intervalle vide. ##### `startswith` Les objets renvoyés possèdent la limite inférieure indiquée. Peut être suivie par des recherches valides pour le champ de base. ``` >>> Event.objects.filter(ages__startswith=21) ]> ``` ##### `endswith` Les objets renvoyés possèdent la limite supérieure indiquée. Peut être suivie par des recherches valides pour le champ de base. ``` >>> Event.objects.filter(ages__endswith=10) ]> ``` ##### `isempty` Les objets renvoyés sont des intervalles vides. Peut être suivie par des recherches valides pour un champ [`BooleanField`](/fr/2.2/ref/models/fields/#django.db.models.BooleanField). ``` >>> Event.objects.filter(ages__isempty=True) ``` ### Définition de ses propres types d’intervalle PostgreSQL permet de définir ses propres types d’intervalle. Les implémentations de champs de modèle et de formulaire de Django utilisent les classes de base ci-dessous, et psycopg2 propose une fonction [`register_range()`](https://www.psycopg.org/docs/extras.html#psycopg2.extras.register_range) pour permettre l’utilisation de types d’intervalle personnalisés. #### `class RangeField(**options)` Classe de base pour les champs de modèle de type intervalle. #### `base_field` La classe de champ de modèle à utiliser. #### `range_type` Le type d’intervalle psycopg2 à utiliser. #### `form_field` La classe de champ de formulaire à utiliser. Doit être une sous-classe de [`django.contrib.postgres.forms.BaseRangeField`](#django.contrib.postgres.fields.django.contrib.postgres.forms.BaseRangeField). #### `class django.contrib.postgres.forms.BaseRangeField` Classe de base pour les champs de formulaire de type intervalle. #### `base_field` Le champ de formulaire à utiliser. #### `range_type` Le type d’intervalle psycopg2 à utiliser.