Skip to content

Commit 1f8a6be

Browse files
authored
Merge pull request #90 from VoidClancy/benchmark
docs(CRUD, pagination, query filters, select,omit): Add docs for CRUD operations, pagination, select & omit, and query filters
2 parents 6a18422 + 2ddc4f2 commit 1f8a6be

18 files changed

Lines changed: 1458 additions & 54 deletions

‎.github/workflows/sync-docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ on:
55
branches: ["main", "master"]
66
paths:
77
- "docs/**"
8+
pull_request:
9+
paths:
10+
- "docs/**"
811
workflow_dispatch:
912

1013
jobs:

‎docs/.prettierrc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"tabWidth": 4,
3+
"useTabs": false,
4+
"printWidth": 100,
5+
"semi": true,
6+
"singleQuote": false,
7+
"quoteProps": "as-needed",
8+
"trailingComma": "all",
9+
"bracketSpacing": true,
10+
"bracketSameLine": false,
11+
"arrowParens": "always",
12+
"endOfLine": "lf"
13+
}

‎docs/Count-Records.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ title: Count Records
33
description: Count the number of records matching a set of predicates.
44
category: CRUD
55
tags: [count, count records]
6-
order: 5
6+
categoryOrder: 2
7+
order: 6
78
---
89

910
# Count Records
@@ -32,9 +33,9 @@ usersCount, err := db.User.
3233

3334
### Supported Builder Methods
3435

35-
| Method | Description |
36-
| --- | --- |
37-
| [`Take`](/docs/Take) | Limit the number of records included in the count. Mirrors SQL's `LIMIT`. |
36+
| Method | Description |
37+
| -------------------- | -------------------------------------------------------------------------- |
38+
| [`Take`](/docs/Take) | Limit the number of records included in the count. Mirrors SQL's `LIMIT`. |
3839
| [`Skip`](/docs/Skip) | Skip a number of matching records before counting. Mirrors SQL's `OFFSET`. |
3940

40-
> **Note:** `Take` and `Skip` affect the result of the count. For example, if 100 records match a predicate and you call `Take(10)`, the returned count will be `10`, not `100`.
41+
> **Note:** `Take` and `Skip` affect the result of the count. For example, if 100 records match a predicate and you call `Take(10)`, the returned count will be `10`, not `100`.

‎docs/Create-Records.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,10 @@ created, err := db.User.Create().
5656

5757
### Supported Builder Methods
5858

59-
| Method | Description |
60-
| --- | --- |
61-
| [`Select`](/docs/Select) | Select specific fields and relations. Mutually exclusive with `Omit`. |
62-
| [`Omit`](/docs/Omit) | Omit specific scalar fields. Mutually exclusive with `Select`. |
59+
| Method | Description |
60+
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
61+
| [`Select`](/docs/Select) | Select specific fields and relations. Mutually exclusive with `Omit`. |
62+
| [`Omit`](/docs/Omit) | Omit specific scalar fields. Mutually exclusive with `Select`. |
6363
| [`OnConflict`](/docs/Upsert-Records#onconflict) | Configure behavior when a unique constraint is violated. Supports `.Ignore()`, `.UpdateNewValues()`, and `.Update()`. |
6464

6565
---
@@ -105,10 +105,10 @@ createdCount, err := db.User.CreateMany(usersToCreate...).Exec(ctx)
105105
106106
### Supported Builder Methods
107107

108-
| Method | Description |
109-
| --- | --- |
108+
| Method | Description |
109+
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
110110
| [`OnConflict`](/docs/Upsert-Records#onconflict) | Configure behavior when a unique constraint is violated. Supports `.Ignore()`, `.UpdateNewValues()`, and `.Update()`. |
111-
| [`SkipDuplicates`](/docs/SkipDuplicates) | Shorthand for `.OnConflict().Ignore()`. |
111+
| [`SkipDuplicates`](/docs/SkipDuplicates) | Shorthand for `.OnConflict().Ignore()`. |
112112

113113
---
114114

@@ -151,9 +151,9 @@ createdUsers, err := db.User.CreateManyAndReturn(usersToCreate...).Exec(ctx)
151151

152152
### Supported Builder Methods
153153

154-
| Method | Description |
155-
| --- | --- |
156-
| [`Select`](/docs/Select) | Select specific fields and relations. Mutually exclusive with `Omit`. |
157-
| [`Omit`](/docs/Omit) | Omit specific scalar fields. Mutually exclusive with `Select`. |
154+
| Method | Description |
155+
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
156+
| [`Select`](/docs/Select) | Select specific fields and relations. Mutually exclusive with `Omit`. |
157+
| [`Omit`](/docs/Omit) | Omit specific scalar fields. Mutually exclusive with `Select`. |
158158
| [`OnConflict`](/docs/Upsert-Records#onconflict) | Configure behavior when a unique constraint is violated. Supports `.Ignore()`, `.UpdateNewValues()`, and `.Update()`. |
159-
| [`SkipDuplicates`](/docs/SkipDuplicates) | Shorthand for `.OnConflict().Ignore()`. |
159+
| [`SkipDuplicates`](/docs/SkipDuplicates) | Shorthand for `.OnConflict().Ignore()`. |

‎docs/Cursor.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: Cursor
3+
description: Fetch pages of results relative to a known record, identified by a unique predicate.
4+
category: Pagination & Sort
5+
tags: [cursor, pagination, keyset]
6+
categoryOrder: 5
7+
order: 4
8+
---
9+
10+
# Cursor
11+
12+
`Cursor` implements cursor-based (keyset) pagination. Instead of skipping an arbitrary number of rows like [`Skip`](/docs/Skip), you position the query _after_ a specific record, identified by a unique predicate such as `user.Email.EQ(...)` or `user.Id.EQ(...)`.
13+
14+
This approach stays stable under concurrent inserts and updates and is far more efficient on large datasets than offset pagination.
15+
16+
`Cursor` can be used with `FindFirst`, `FindMany`, and nested relation query builders. It is typically combined with [`OrderBy`](/docs/OrderBy) and [`Take`](/docs/Take).
17+
18+
## Fetching the Next Page
19+
20+
Combine a cursor with a positive [`Take`](/docs/Take) to fetch the page following a known record:
21+
22+
```go
23+
nextPage, err := db.User.
24+
FindMany(user.Email.Contains("@example.com")).
25+
OrderBy(user.Email.Asc()).
26+
Cursor(user.Email.EQ(lastEmail)).
27+
Take(20).
28+
Exec(ctx)
29+
```
30+
31+
This returns the next 20 records after `lastEmail`.
32+
33+
## Fetching the Previous Page
34+
35+
Combine a cursor with a negative [`Take`](/docs/Take) to fetch the records that precede it:
36+
37+
```go
38+
prevPage, err := db.User.
39+
FindMany(user.Email.Contains("@example.com")).
40+
OrderBy(user.Email.Asc()).
41+
Cursor(user.Email.EQ(firstEmailOfCurrentPage)).
42+
Take(-20).
43+
Exec(ctx)
44+
```
45+
46+
> **Note:** The cursor value must reference a unique field, such as the record's `Id` or another unique column.
47+
48+
## Usage Tips
49+
50+
- Always provide a stable [`OrderBy`](/docs/OrderBy); it must be consistent from page to page.
51+
- Pass the last record of the current page as the cursor for the next page, and the first record for the previous page.
52+
- Use [`Skip`](/docs/Skip) together with a cursor when you want to jump a fixed number of rows past the cursor.
53+
54+
## Supported By
55+
56+
- [`FindMany`](/docs/Read-Records#findmany)
57+
- [`FindFirst`](/docs/Read-Records#findfirst)
58+
- Nested relation queries via [`Select`](/docs/Select)
59+
60+
## Resulting SQL
61+
62+
A cursor query compiles into a key-based comparison on the cursor's column, combined with the ordering and limit:
63+
64+
```sql
65+
SELECT * FROM "users"
66+
WHERE "email" > 'last@example.com'
67+
ORDER BY "email" ASC
68+
LIMIT 20;
69+
```
70+
71+
A negative [`Take`](/docs/Take) swaps the comparison direction to fetch preceding rows.

‎docs/Delete-Records.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: Delete Records
3+
description: Delete one or more records using type-safe delete builders.
4+
category: CRUD
5+
tags: [delete, deleteMany]
6+
categoryOrder: 2
7+
order: 4
8+
---
9+
10+
# Delete Records
11+
12+
Phi provides two methods for deleting records:
13+
14+
- `Delete`
15+
- `DeleteMany`
16+
17+
> **Note:** `Delete` always returns the deleted record, regardless of the underlying database. On databases that support `DELETE ... RETURNING`, Phi performs the deletion in a single query. On databases that don't, Phi transparently executes the operation inside a transaction by fetching the record before deleting it, ensuring consistent behavior across all supported SQL dialects.
18+
19+
---
20+
21+
## Delete
22+
23+
Deletes a **single record**.
24+
25+
The first predicate **must** uniquely identify a record (for example, `Id.EQ()` or another unique field). Additional predicates may be supplied to further constrain the deletion.
26+
27+
By default, all scalar fields are returned. Use `Select` or `Omit` to customize the returned data.
28+
29+
### Basic
30+
31+
```go
32+
user, err := db.User.Delete(
33+
user.Email.EQ("x@y.com"),
34+
).Exec(ctx)
35+
```
36+
37+
### With Additional Predicates
38+
39+
```go
40+
user, err := db.User.Delete(
41+
user.Email.EQ("x@y.com"),
42+
user.Bio.Contains("golang"),
43+
).Exec(ctx)
44+
```
45+
46+
### Returning Selected Fields
47+
48+
```go
49+
user, err := db.User.Delete(
50+
user.Id.EQ(id),
51+
).
52+
Select(user.Select{
53+
Id: true,
54+
Username: true,
55+
}).
56+
Exec(ctx)
57+
```
58+
59+
### Omitting Fields
60+
61+
```go
62+
user, err := db.User.Delete(
63+
user.Id.EQ(id),
64+
).
65+
Omit(user.Omit{
66+
Password: true,
67+
}).
68+
Exec(ctx)
69+
```
70+
71+
### Supported Builder Methods
72+
73+
| Method | Description |
74+
| ------------------------ | ------------------------------------------------- |
75+
| [`Select`](/docs/Select) | Return only the selected fields and relations. |
76+
| [`Omit`](/docs/Omit) | Return all scalar fields except the omitted ones. |
77+
78+
---
79+
80+
## DeleteMany
81+
82+
Deletes **all records** matching the supplied predicates.
83+
84+
Unlike `Delete`, no unique predicate is required.
85+
86+
`DeleteMany` returns the number of rows deleted.
87+
88+
### Basic
89+
90+
```go
91+
deleted, err := db.User.DeleteMany(
92+
user.Bio.Contains("inactive"),
93+
).Exec(ctx)
94+
```
95+
96+
### Multiple Predicates
97+
98+
```go
99+
deleted, err := db.User.DeleteMany(
100+
user.Email.HasSuffix("@example.com"),
101+
user.LoginCount.LT(5),
102+
).Exec(ctx)
103+
```
104+
105+
### Using Logical Predicates
106+
107+
```go
108+
deleted, err := db.User.DeleteMany(
109+
user.Or(
110+
user.Bio.Contains("spam"),
111+
user.PhoneNum.HasPrefix("+999"),
112+
),
113+
).Exec(ctx)
114+
```
115+
116+
### Return Value
117+
118+
```go
119+
deleted, err := db.User.DeleteMany(
120+
user.Bio.Contains("inactive"),
121+
).Exec(ctx)
122+
123+
fmt.Printf("Deleted %d users\n", deleted)
124+
```
125+
126+
### Supported Builder Methods
127+
128+
`DeleteMany` exposes no additional builder methods beyond its predicates.
129+
130+
> **Note:** `DeleteMany` only returns the number of deleted rows. If you need the deleted records themselves, query them before deleting.

‎docs/Omit.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Omit
3+
description: Omit specific scalar fields from a query result.
4+
category: Select & Omit
5+
tags: [omit, omit fields, scalar selection]
6+
categoryOrder: 3
7+
order: 2
8+
---
9+
10+
# Omit
11+
12+
`Omit` specifies which scalar fields should be excluded from a query result.
13+
14+
Unlike `Select`, `Omit` only applies to scalar fields. Relations are never loaded unless explicitly selected with `Select`.
15+
16+
## Omitting Scalar Fields
17+
18+
Omit scalar fields by setting their corresponding field to `true`. Set a field to `false` (or leave it unset) to include it in the result.
19+
20+
```go
21+
users, err := db.User.
22+
FindMany(user.Email.EQ("x@y.com")).
23+
Omit(user.Omit{
24+
Id: true,
25+
Email: true,
26+
Bio: true,
27+
}).
28+
Exec(ctx)
29+
```
30+
31+
> **Note:** `Select` and `Omit` are mutually exclusive. Attempting to use both on the same query will result in an error.
32+
33+
## Supported By
34+
35+
`Omit` is supported by:
36+
37+
- [`Create`](/docs/Create-Records#create)
38+
- [`CreateManyAndReturn`](/docs/Create-Records#createmanyandreturn)
39+
- [`FindUnique`](/docs/Read-Records#findunique)
40+
- [`FindFirst`](/docs/Read-Records#findfirst)
41+
- [`FindMany`](/docs/Read-Records#findmany)
42+
- [`Update`](/docs/Update-Records#update)
43+
- [`UpdateManyAndReturn`](/docs/Update-Records#updatemanyandreturn)
44+
- [`Delete`](/docs/Delete-Records#delete)

0 commit comments

Comments
 (0)