Repository navigation
2.0.0
Breaking Changes
EAV2_PRIMARY_KEY_FIELDaccepts onlydjango.db.models.BigAutoField(the default) anddjango.db.models.UUIDField.django.db.models.CharField,django.db.models.AutoFieldand any other value now raiseImproperlyConfiguredinstead of being ignored. ACharFieldkey never worked on its own, because nothing generates the ids; it only existed as the middle step of a conversion described in the README.- Migrations
0001and0010use the configured key type, so a new project withUUIDFieldgets UUID keys from its firstmigrate; this fixescannot cast type bigint to uuidon PostgreSQL (#455). Existing databases are unaffected. The README's two-step conversion, which generated migration files inside the installed package, is gone: converting the keys of existing tables is not supported. order_by("eav__<enum attribute>")now sorts by the text of the choice, so it does not depend on how the database orders keys. It used to sort by the choice's id.
Deprecations
- The
json,csv, andobjectattribute datatypes are deprecated and django-eav2 3.0 removes them, along with their value columns. Saving an attribute of one of these types, or writing a value to one (includingbulk_create()andbulk_update()), emitseav.exceptions.RemovedInEav3Warning, aFutureWarningthat points at your own code. Use aJSONField, aForeignKey, aManyToManyField, or a related model on your own model instead, and move existing data out of EAV before 3.0. If you have a use case that those do not cover, open an issue.
Performance
instance.eav.<slug>loads an entity's attributes and values once and reuses them, so reading three attributes takes 2 queries instead of 6. The values are held in the instance'sprefetch_relatedcache, sorefresh_from_db()andsave()clear them; useinstance.eav.clear_cache()after changing values elsewhere.- Saving an entity loads its attributes and values once and writes only assigned values: creating an entity with three attributes takes 6 queries instead of 39, and saving one changed attribute takes 4 instead of 11.
prefetch_related("eav_values__attribute")is now used when reading attributes, and entities from one queryset (including.iterator()) share a single attribute lookup. Reading one attribute across 10 prefetched entities takes 3 queries instead of 23.EavConfig.cache_values = Falseturns the value cache off for a model, so every read queries the database. Use it, orinstance.eav.clear_cache(), when values are written outsideinstance.eavandsave(), such as withValue.objects.bulk_create: cached reads do not see those writes.- New
Attribute.store_value,Value.save_checked,Entity.clear_cacheandEavConfig.shares_attributes;Attribute.save_valuekeeps its behaviour. - Migration
0013adds indexes on(attribute, value_int),(attribute, value_float),(attribute, value_date)and(attribute, value_enum), so filters such aseav__age__gt=5andeav__score=500read the matching rows instead of every value of the attribute. On a table of 500,000 values an equality filter took 0.3 ms instead of 6.5 ms and a range filter 7 ms instead of 13 ms. Text values are not indexed.
Features
bulk_create()andbulk_update()on EAV managers store EAV values in about one query per 1000 rows instead of one or more per entity:Patient.objects.bulk_create(patients)writes the values assigned withpatient.eav.<slug> = ..., andbulk_update(patients, ["name", "eav__age"])updates them. Instances are validated first, written in chunks inside one transaction, and no signals are sent. Creating entities needs primary keys, so integer keys are not supported on MySQL.EavConfig.bulk_batch_size(1000 by default) sets how many entitiesbulk_create()andbulk_update()write at a time; thebatch_sizeargument overrides it.Attribute.enum_choices,Attribute.validate_assignment,Entity.assigned_valuesandValue.clean_own_fields. Saving an enum attribute no longer queries the choices more than once.
Bug Fixes
~Q()on an attribute inside a largerQremoves whole entities, asexclude()does. It used to negate single value rows, sofilter(Q(eav__age__gt=30) & ~Q(eav__city="Nice"))could return entities that live in Nice. Every condition on an attribute, in aQor as a keyword argument, is now an independentEXISTSsubquery, which also stops OR conditions from returning an entity more than once.eav__<slug>__isnull=Truefinds the entities that have no value for the attribute. It used to find nothing.- Lookups chained after an attribute slug, such as
eav__born__year__gt=2000oreav__extras__chills__iexact="yes", are applied. They used to be dropped, which returned no rows. filter()no longer changes theQobjects you pass to it, so you can reuse them, and aQthat contains an expression such asExists(...)no longer fails.- A lookup other than equality on an
objectattribute raisesFieldError. It used to be ignored, which returned wrong rows. - Unregistering a model removes its generic relation, and the matching reverse relation on
Value. It used to leave the relation behind, and everyregister()after anunregister()added another copy of it to the model. BaseEntityInlineworks: it used to fail withAttributeErrorwhen the inline had noform, and withFieldErrorwhen it had aBaseDynamicEntityForm. The inline now defaults toBaseDynamicEntityForm, shows the attributes of its own model, saves them, and honorsfields. An attribute named like a reverse relation of the inline's model no longer fails.- The change page of a model that uses
BaseEntityAdminopens for users who only have the view permission. It used to fail withKeyError. - Filtering on several EAV attributes in one
filter()call works on UUID-keyed entities. - The Indonesian translation is compiled and ships with the package; its
.mofile was missing. A test now fails if any compiled catalog differs from its.posource. validate_enumandvalidate_objectuse Django's_state.addingto detect unsaved instances, because a model with a UUID default key always has a primary key, so an unsavedEnumValuewas accepted and then failed with an integrity error.Value.entity_idandValue.generic_value_idare nowBigIntegerField, so entities with primary keys above 2,147,483,647 can store values (migration0014). On PostgreSQL and MySQL this rewrites theeav_valuetable, which takes a lock for as long as the rewrite runs on a large table, so plan the upgrade accordingly.- Assigning a plain
dateto a date attribute stores midnight in the default timezone, as before, but no longer emits Django's "naive datetime"RuntimeWarningwhenUSE_TZis on, and saving the same date again no longer rewrites the value. order_by("eav__<slug>")no longer fails on UUID-keyed entities or empty querysets, no longer mixes in values of other models that share a primary key, and now accepts-eav__<slug>for descending order. Ordering by anobjectattribute raisesNotSupportedError(it was aFieldError). Ordering by a related field such asorder_by("example__name")now sorts by that field; it used to sort by the foreign key column only.validate_intandvalidate_floatraiseValidationErrorinstead ofTypeErrorforNoneand other non-numeric types.- An empty CSV value is read back as
[]instead of['']. BaseEntityInline.get_fieldsetsno longer recurses infinitely, and honoursfieldsets.EAV2_PRIMARY_KEY_FIELDdefaults toBigAutoFieldwhen it is not set, instead of raisingAttributeError.- Unknown attribute slugs raise
Attribute.DoesNotExistwith the same message fromfilter,exclude,getandorder_by. Entity.get_valuesnames the related fields it loads, which removes a Django 6.1 deprecation warning.
Full Changelog: 1.8.2...2.0.0