Hydration Primitives — Aquilia Documentation
Comprehensive guide and documentation for Hydration Primitives in the Aquilia framework. View API reference, examples, and implementation patterns.
Docs / Models / Hydration Primitives Hydration Primitives Aquilia's database driver is 100% async. Python descriptors are synchronous, meaning transparent lazy loading of relations on attribute access is impossible. Relationships must be explicitly hydrated. The RelatedNotLoaded Sentinel Accessing a relationship attribute that has not been hydrated returns a RelatedNotLoaded[TModel] instance. This wraps the raw foreign key value and supports no-query operations: post = await Post.objects.get(id=42) # Checking truthiness (is FK set?) — works without query if post.author: print("FK is not null") # Reading the raw PK value — works without query print(post.author.pk) # e.g., 9 print(post.author.id) # e.g., 9 # Comparing by PK — works without query if post.author == existing_user: print("Same user!") # Any other attribute access raises RelatedNotLoadedFault! try: print(post.author.name) except RelatedNotLoadedFault as e: print("Relation not loaded yet!") How to Hydrate Relations 1. Eager JOIN (select_related) Hydrates single relations (ForeignKey, OneToOneField) inside a single SQL query via a JOIN statement: # Single SQL JOIN query posts = await Post.objects.select_related("author").all() for post in posts: print(post.author.name) # No extra query! 2. Eager Batch (prefetch_related) Hydrates relations (including ManyToMany or reverse ForeignKey) using a separate query per relation, mapping results in Python: # Multi-query batching posts = await Post.objects.prefetch_related("tags").all() for post in posts: for tag in post.tags: print(tag.name) 3. Explicit Fetch (related) Loads and caches a relation on a specific instance explicitly: # Fetch and cache relation instance-level author = await post.related("author") print(author.name) Static Typing Contract Relational attributes resolve to a union type alias: Related[UserModel], which translates to: Union[UserModel, RelatedNotLoaded[UserModel], None] Annotate string-referenced relation attributes to restore strict IDE autocompletion: class Post(Model): # Required for string references author: ForeignKey[User] = ForeignKey("User", on_delete="CASCADE") Defining Relations Many-to-Many Operations )
Go to Homepage