From 15ed075de395e5dc80ad4f6ca416997a45e0bf04 Mon Sep 17 00:00:00 2001
From: Jonas Perusquia Morales <jonaspm@enerlinq.com>
Date: Wed, 17 Dec 2025 09:35:24 -0600
Subject: [PATCH] docs: Document data.readOneBy method with usage examples

---
 .../docs/(documentation)/usage/sdk.mdx        | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/content/docs/(documentation)/usage/sdk.mdx b/docs/content/docs/(documentation)/usage/sdk.mdx
index f2537d7..0d5d3d3 100644
--- a/docs/content/docs/(documentation)/usage/sdk.mdx
+++ b/docs/content/docs/(documentation)/usage/sdk.mdx
@@ -137,6 +137,35 @@ To retrieve a single record from an entity, use the `readOne` method:
 const { data } = await api.data.readOne("posts", 1);
 ```
 
+### `data.readOneBy([entity], [query])`
+
+To retrieve a single record from an entity using a query (e.g., by a specific field value) instead of an ID, use the `readOneBy` method:
+
+```ts
+const { data } = await api.data.readOneBy("posts", {
+  where: {
+    slug: "hello-world",
+  },
+});
+```
+
+This is useful when you want to find a record by a unique field other than the primary key. You can also use `select`, `with`, and `join` options:
+
+```ts
+const { data } = await api.data.readOneBy("users", {
+  select: ["id", "email", "name"],
+  where: {
+    email: "user@example.com",
+  },
+  with: {
+    posts: {
+      limit: 5,
+    },
+  },
+  join: ["profile"],
+});
+```
+
 ### `data.createOne([entity], [data])`
 
 To create a single record of an entity, use the `createOne` method: