Champs de modèles spécifiques à PostgreSQLLien vers cette rubrique#

containsLien vers cette rubrique#

La recherche contains est surchargée pour 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: First post>, <Post: Second post>]

>>> Post.objects.filter(tags__contains=['django'])
[<Post: First post>, <Post: Third post>]

>>> Post.objects.filter(tags__contains=['django', 'thoughts'])
[<Post: First post>]

contained_byLien vers cette rubrique#

Il s’agit de l’inverse de la recherche 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: First post>, <Post: Second post>]

>>> Post.objects.filter(tags__contained_by=['thoughts', 'django', 'tutorial'])
[<Post: First post>, <Post: Second post>, <Post: Third post>]

overlapLien vers cette rubrique#

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: First post>, <Post: Second post>]

>>> Post.objects.filter(tags__overlap=['thoughts', 'tutorial'])
[<Post: First post>, <Post: Second post>, <Post: Third post>]

lenLien vers cette rubrique#

Renvoie la longueur du tableau. Les recherches disponibles à la suite de celle-ci sont celles qui sont disponibles pour les champs 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)
[<Post: Second post>]

Transformations d’indiceLien vers cette rubrique#

Cette classe de transformations permet d’indicer les tableaux dans les requêtes. Tout nombre entier non négatif est utilisable. Aucune erreur n’est produite si l’indice dépasse la taille size du tableau. Les recherches disponibles à la suite de la transformation sont celles du champ 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: First post>, <Post: Second post>]

>>> Post.objects.filter(tags__1__iexact='Django')
[<Post: First post>]

>>> Post.objects.filter(tags__276='javascript')
[]

Transformations de segmentationLien vers cette rubrique#

Cette classe de transformation permet de segmenter un tableau. 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: First post>, <Post: Second post>]

>>> Post.objects.filter(tags__0_2__contains=['thoughts'])
[<Post: First post>, <Post: Second post>]

Recherches par cléLien vers cette rubrique#

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')
[<Dog: Meg>]

Il est possible d’enchaîner d’autres recherches après une recherche par clé :

>>> Dog.objects.filter(data__breed__contains='l')
[<Dog: Rufus>, <Dog: Meg>]

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 à la place.

containsLien vers cette rubrique#

La recherche contains est surchargée pour 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: Rufus>, <Dog: Meg>]

>>> Dog.objects.filter(data__contains={'breed': 'collie'})
[<Dog: Meg>]

contained_byLien vers cette rubrique#

Il s’agit de l’inverse de la recherche 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: Meg>, <Dog: Fred>]

>>> Dog.objects.filter(data__contained_by={'breed': 'collie'})
[<Dog: Fred>]

has_keyLien vers cette rubrique#

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')
[<Dog: Meg>]

has_any_keysLien vers cette rubrique#

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'])
[<Dog: Rufus>, <Dog: Meg>]

has_keysLien vers cette rubrique#

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'])
[<Dog: Meg>]

keysLien vers cette rubrique#

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. 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'])
[<Dog: Rufus>, <Dog: Meg>]

valuesLien vers cette rubrique#

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. 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'])
[<Dog: Meg>]

Interrogations de clé, d’indice et de cheminLien vers cette rubrique#

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'})

>>> Dog.objects.filter(data__breed='collie')
[<Dog: Meg>]

Il est possible d’enchaîner plusieurs clés pour former une recherche de chemin :

>>> Dog.objects.filter(data__owner__name='Bob')
[<Dog: Rufus>]

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')
[<Dog: Rufus>]

Si la clé avec laquelle vous souhaitez rechercher entre en conflit avec le nom d’une recherche existante, utilisez la recherche 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é.

Opérations de contenance et de cléLien vers cette rubrique#

JSONField partage les interrogations liées à la contenance et aux clés avec le champ HStoreField.

• contains (accepte n’importe quel JSON et pas seulement un dictionnaire de chaînes)

• contained_by (accepte n’importe quel JSON et pas seulement un dictionnaire de chaînes)

• has_key

• has_any_keys

• has_keys

Fonctions de contenanceLien vers cette rubrique#

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 &&.

>>> Event.objects.filter(ages__contains=NumericRange(4, 5))
[<Event: Soft play>]

>>> Event.objects.filter(ages__contained_by=NumericRange(0, 15))
[<Event: Soft play>]

>>> from psycopg2.extras import DateTimeTZRange
>>> Event.objects.filter(start__contained_by=DateTimeTZRange(
...     timezone.now() - datetime.timedelta(hours=1),
...     timezone.now() + datetime.timedelta(hours=1),
... )
[<Event: Soft play>]

>>> Event.objects.filter(ages__overlap=NumericRange(8, 12))
[<Event: Soft play>]

Fonctions de comparaisonLien vers cette rubrique#

Les champs d’intervalle prennent en charge les recherches standard : lt, gt, lte et 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.

>>> Event.objects.filter(ages__fully_lt=NumericRange(11, 15))
[<Event: Soft play>]

>>> Event.objects.filter(ages__fully_gt=NumericRange(11, 15))
[<Event: Pub trip>]

>>> Event.objects.filter(ages__not_lt=NumericRange(0, 15))
[<Event: Soft play>, <Event: Pub trip>]

>>> Event.objects.filter(ages__not_gt=NumericRange(3, 10))
[<Event: Soft play>]

>>> Event.objects.filter(ages__adjacent_to=NumericRange(10, 21))
[<Event: Soft play>, <Event: Pub trip>]

Interrogation à l’aide des limitesLien vers cette rubrique#

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.

>>> Event.objects.filter(ages__startswith=21)
[<Event: Pub trip>]

>>> Event.objects.filter(ages__endswith=10)
[<Event: Soft play>]

>>> Event.objects.filter(ages__isempty=True)
[]

Définition de ses propres types d’intervalleLien vers cette rubrique#

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() pour permettre l’utilisation de types d’intervalle personnalisés.

class RangeField(**options)Lien vers cette définition#

Classe de base pour les champs de modèle de type intervalle.

base_fieldLien vers cette définition#

Le champ de modèle à utiliser.

range_typeLien vers cette définition#

Le type d’intervalle psycopg2 à utiliser.

form_fieldLien vers cette définition#

La classe de champ de formulaire à utiliser. Doit être une sous-classe de django.contrib.postgres.forms.BaseRangeField.

class django.contrib.postgres.forms.BaseRangeFieldLien vers cette définition#

Classe de base pour les champs de formulaire de type intervalle.

base_fieldLien vers cette définition#

Le champ de formulaire à utiliser.

range_typeLien vers cette définition#

Le type d’intervalle psycopg2 à utiliser.