Documentation and announcement blog for relationship queries

.optimize-cache.json

@@ -179,6 +179,7 @@
   "images/blog/announcing-new-push-notifications-features/cover.png": "a0c758cf6c8a95e09a0d2ca562b0775a50d34a4d691d675cda70e44ad21805ac",
   "images/blog/announcing-opt-in-relationship-loading/cover.png": "e16cc16ea6d968b29af19bcd6274741141584a7efe5e1bb18be19b77c3a380c8",
   "images/blog/announcing-phone-OTP-pricing/cover.png": "598d55359ca4cb2b46846a8fd76b1f051be7c5f3199b50ffa92a28e84e5f3d67",
+  "images/blog/announcing-relationship-queries/cover.png": "7e615c0a9dcbb3949d5fb7ed71f36bb44de40ae67c8cd832b96ff5bbd4b0f451",
   "images/blog/announcing-screenshots-api/cover.png": "56555006946b9ead5cd4258544b6a9dda44bce6841706749f7539bc31356383e",
   "images/blog/announcing-spatial-columns/cover.png": "b3e73629df86190fb06b715f4fe24aad473631538c1b3e78ae45cc8c5e7cd7d0",
   "images/blog/announcing-time-helper-queries/cover.png": "0ee1d4d1edc65bf8fc3376b761b08efaffa55dd8ca84860ab3a9c34f7d78c25b",

src/routes/blog/post/announcing-relationship-queries/+page.markdoc

@@ -0,0 +1,72 @@
+---
+layout: post
+title: "Announcing relationship queries: Filter across related data with ease"
+description: You can now use filter queries directly on relationship columns, plus enjoy up to 18x faster relationship performance across the board.
+date: 2026-02-06
+cover: /images/blog/announcing-relationship-queries/cover.png
+timeToRead: 5
+author: jake-barnby
+category: announcement
+featured: false
+---
+
+If you've worked with relationships in Appwrite, you've likely run into two pain points: they presented performance challenges, and you couldn't query across them. If you wanted to find all posts by a specific author or all orders containing a certain product, you had to fetch everything and filter in your application layer.
+
+Both of those problems are now solved.
+
+As of today, Appwrite Databases supports **filter queries on relationship columns** and delivers a **12-18x performance improvement** for relationship operations. Relationships are no longer just a way to connect data, they're now a fast, queryable foundation you can build on with confidence.
+
+# Querying relationships
+
+You can now use filter queries directly against relationship columns using dot notation. Reference fields on related rows with the format `relationshipKey.field`, and Appwrite handles the rest.
+
+```js
+const { Client, TablesDB, Query } = require('node-appwrite');
+
+const client = new Client()
+    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
+    .setProject('<PROJECT_ID>');
+
+const tablesDB = new TablesDB(client);
+
+// Get all posts where the author's name is 'Jake'
+await tablesDB.listRows({
+    databaseId: 'blog',
+    tableId: 'posts',
+    queries: [
+        Query.equal('author.name', ['Jake'])
+    ],
+});
+```
+
+All [comparison operators](/docs/products/databases/queries#comparison) are supported, including `equal`, `notEqual`, `greaterThan`, `lessThan`, `between`, `contains`, and the full set of spatial queries.
+
+# 12-18x faster relationship performance
+
+Alongside query support, we've overhauled the internals of how relationships are resolved, delivering a consistent **12-18x speed improvement** for relationship operations.
+
+Whether you're loading a user's posts, an order's line items, or a project's team members, the response comes back faster across the board.
+
+These performance gains apply automatically. There's nothing to configure or opt into. If you're already using relationships, they just got faster.
+
+# What this unlocks
+
+With queryable, high-performance relationships, you can now build patterns that were previously impractical:
+
+- **Filtered views across tables:** Show all articles by authors in a specific country, or all products in a category with stock above zero.
+- **Search with context:** Find users whose organization matches a criteria, without fetching and filtering client-side.
+- **Dashboards and reports:** Aggregate and filter data across related tables directly in your queries.
+- **Faster applications:** Reduced response times mean snappier UIs, especially for pages that load multiple levels of related data.
+
+# Availability
+
+Relationship queries and performance improvements are available now on both **Appwrite Cloud** and **self-hosted**.
+
+If you've been working around the limitations of relationships, now is a great time to revisit your data model. Queries across relationships and dramatically faster performance make them a first-class tool for building connected, real-world data structures.
+
+# More resources
+
+- [Read the relationships documentation](/docs/products/databases/relationships)
+- [Learn about queries in Appwrite Databases](/docs/products/databases/queries)
+- [Announcing opt-in relationship loading](/blog/post/announcing-opt-in-relationship-loading)
+- [Announcing API for spatial columns: Build scalable location-aware apps with ease](/blog/post/announcing-spatial-columns)

src/routes/docs/products/databases/relationships/+page.markdoc

@@ -27,10 +27,6 @@ Relationships help reduce redundant information. For example, a user can create
 
 Duplicated records waste storage, but more importantly, makes the database much harder to maintain. If the user changes their user name, you will have to update dozens or hundreds of records, a problem commonly known as an update anomaly in tablesDB. You can avoid duplicate information by storing users and posts in separate tables and relating a user and their posts through a relationship.
 
-# Tradeoffs {% #trade-offs %}
-
-Consider using relationships when the same information is found in multiple places to avoid duplicates. However, relationships come with the tradeoff of slowing down queries. For applications where the best read and write performance is important, it may be acceptable to tolerate duplicate data.
-
 # Opt-in loading {% #performance-loading %}
 
 By default, Appwrite returns only a row's own fields when you retrieve rows. Related rows are **not automatically loaded** unless you explicitly request them using query selection. This eliminates unintentional payload bloat and gives you precise control over performance.
@@ -514,7 +510,92 @@ tablesDB.createRow(
 {% /tabs %}
 
 # Queries {% #queries %}
-Queries are currently not available in the experimental version of Appwrite Relationships but will be added in a later version.
+
+You can use filter queries directly against relationship columns using dot notation. This lets you filter rows based on the values of their related rows, such as filtering posts by an author's name or filtering orders by a product's category.
+
+Use the format `relationshipKey.field` to reference fields on related rows.
+
+{% multicode %}
+```js
+const { Client, TablesDB, Query } = require('node-appwrite');
+
+const client = new Client()
+    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
+    .setProject('<PROJECT_ID>');               // Your project ID
+
+const tablesDB = new TablesDB(client);
+
+await tablesDB.listRows({
+    databaseId: 'marvel',
+    tableId: 'movies',
+    queries: [
+        Query.equal('reviews.author', ['Bob'])
+    ],
+});
+```
+
+```dart
+import 'package:appwrite/appwrite.dart';
+
+final client = Client()
+    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
+    .setProject('<PROJECT_ID>');
+
+final tablesDB = TablesDB(client);
+
+await tablesDB.listRows(
+  databaseId: 'marvel',
+  tableId: 'movies',
+  queries: [
+    Query.equal('reviews.author', ['Bob']),
+  ],
+);
+```
+
+```swift
+import Appwrite
+
+let client = Client()
+    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
+    .setProject("<PROJECT_ID>")
+
+let tablesDB = TablesDB(client)
+
+tablesDB.listRows(
+    databaseId: "marvel",
+    tableId: "movies",
+    queries: [
+        Query.equal("reviews.author", value: ["Bob"])
+    ]
+)
+```
+
+```kotlin
+import io.appwrite.Client
+import io.appwrite.services.TablesDB
+import io.appwrite.Query
+
+val client = Client()
+    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
+    .setProject("<PROJECT_ID>")
+
+val tablesDB = TablesDB(client)
+
+tablesDB.listRows(
+    databaseId = "marvel",
+    tableId = "movies",
+    queries = listOf(
+        Query.equal("reviews.author", listOf("Bob"))
+    )
+)
+```
+{% /multicode %}
+
+All filter queries are supported on relationship fields, including `equal`, `notEqual`, `greaterThan`, `lessThan`, `between`, `contains`, and other [comparison operators](/docs/products/databases/queries#comparison).
+
+{% arrow_link href="/docs/products/databases/queries#relationship-select" %}
+Learn how to select and load relationship data
+{% /arrow_link %}
 
 # Update relationships {% #update %}
 Relationships can be updated by updating the relationship column.