Initial commit
This commit is contained in:
St. Nebula
@@ -0,0 +1,357 @@
|
||||
# Operations Reference
|
||||
|
||||
## Contents
|
||||
- [Generated Fields](#generated-fields)
|
||||
- [Queries](#queries)
|
||||
- [Mutations](#mutations)
|
||||
- [Key Scalars](#key-scalars)
|
||||
- [Multi-Step Operations](#multi-step-operations)
|
||||
|
||||
---
|
||||
|
||||
## Generated Fields
|
||||
|
||||
Data Connect auto-generates fields for each `@table` type:
|
||||
|
||||
| Generated Field | Purpose | Example |
|
||||
|-----------------|---------|---------|
|
||||
| `movie(id: UUID, key: Key, first: Row)` | Get single record | `movie(id: $id)` or `movie(first: {where: ...})` |
|
||||
| `movies(where: ..., orderBy: ..., limit: ..., offset: ..., distinct: ..., having: ...)` | List/filter records | `movies(where: {...})` |
|
||||
| `movie_insert(data: ...)` | Create record | Returns key |
|
||||
| `movie_insertMany(data: [...])` | Bulk create | Returns keys |
|
||||
| `movie_update(id: ..., data: ...)` | Update by ID | Returns key or null |
|
||||
| `movie_updateMany(where: ..., data: ...)` | Bulk update | Returns count |
|
||||
| `movie_upsert(data: ...)` | Insert or update | Returns key |
|
||||
| `movie_delete(id: ...)` | Delete by ID | Returns key or null |
|
||||
| `movie_deleteMany(where: ...)` | Bulk delete | Returns count |
|
||||
|
||||
### Relation Fields
|
||||
For a `Post` with `author: User!`:
|
||||
- `post.author` - Navigate to related User
|
||||
- `user.posts_on_author` - Reverse: all Posts by User
|
||||
|
||||
For many-to-many via `MovieActor`:
|
||||
- `movie.actors_via_MovieActor` - Get all actors
|
||||
- `actor.movies_via_MovieActor` - Get all movies
|
||||
|
||||
---
|
||||
|
||||
## Queries
|
||||
|
||||
### Basic Query
|
||||
|
||||
```graphql
|
||||
query GetMovie($id: UUID!) @auth(level: PUBLIC) {
|
||||
movie(id: $id) {
|
||||
id title genre releaseYear
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List with Filtering
|
||||
|
||||
```graphql
|
||||
query ListMovies($genre: String, $minRating: Int) @auth(level: PUBLIC) {
|
||||
movies(
|
||||
where: {
|
||||
genre: { eq: $genre },
|
||||
rating: { ge: $minRating }
|
||||
},
|
||||
orderBy: [{ releaseYear: DESC }, { title: ASC }],
|
||||
limit: 20,
|
||||
offset: 0
|
||||
) {
|
||||
id title genre rating
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Filter Operators
|
||||
|
||||
| Operator | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `eq` | Equals | `{ title: { eq: "Matrix" }}` |
|
||||
| `ne` | Not equals | `{ status: { ne: "deleted" }}` |
|
||||
| `gt`, `ge` | Greater than (or equal) | `{ rating: { ge: 4 }}` |
|
||||
| `lt`, `le` | Less than (or equal) | `{ releaseYear: { lt: 2000 }}` |
|
||||
| `in` | In list | `{ genre: { in: ["Action", "Drama"] }}` |
|
||||
| `nin` | Not in list | `{ status: { nin: ["deleted", "hidden"] }}` |
|
||||
| `isNull` | Is null check | `{ description: { isNull: true }}` |
|
||||
| `contains` | String contains | `{ title: { contains: "war" }}` |
|
||||
| `startsWith` | String starts with | `{ title: { startsWith: "The" }}` |
|
||||
| `endsWith` | String ends with | `{ email: { endsWith: "@gmail.com" }}` |
|
||||
| `includes` | Array includes | `{ tags: { includes: "sci-fi" }}` |
|
||||
|
||||
### Expression Operators (Compare with Server Values)
|
||||
|
||||
Use `_expr` suffix to compare with server-side values:
|
||||
|
||||
```graphql
|
||||
query MyPosts @auth(level: USER) {
|
||||
posts(where: { authorUid: { eq_expr: "auth.uid" }}) {
|
||||
id title
|
||||
}
|
||||
}
|
||||
|
||||
query RecentPosts @auth(level: PUBLIC) {
|
||||
posts(where: { publishedAt: { lt_expr: "request.time" }}) {
|
||||
id title
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Logical Operators
|
||||
|
||||
```graphql
|
||||
query ComplexFilter($genre: String, $minRating: Int) @auth(level: PUBLIC) {
|
||||
movies(where: {
|
||||
_or: [
|
||||
{ genre: { eq: $genre }},
|
||||
{ rating: { ge: $minRating }}
|
||||
],
|
||||
_and: [
|
||||
{ releaseYear: { ge: 2000 }},
|
||||
{ status: { ne: "hidden" }}
|
||||
],
|
||||
_not: { genre: { eq: "Horror" }}
|
||||
}) { id title }
|
||||
}
|
||||
```
|
||||
|
||||
### Relational Queries
|
||||
|
||||
```graphql
|
||||
# Navigate relationships
|
||||
query MovieWithDetails($id: UUID!) @auth(level: PUBLIC) {
|
||||
movie(id: $id) {
|
||||
title
|
||||
# One-to-one
|
||||
metadata: movieMetadata_on_movie { director }
|
||||
# One-to-many
|
||||
reviews: reviews_on_movie { rating user { name }}
|
||||
# Many-to-many
|
||||
actors: actors_via_MovieActor { name }
|
||||
}
|
||||
}
|
||||
|
||||
# Filter by related data
|
||||
query MoviesByDirector($director: String!) @auth(level: PUBLIC) {
|
||||
movies(where: {
|
||||
movieMetadata_on_movie: { director: { eq: $director }}
|
||||
}) { id title }
|
||||
}
|
||||
```
|
||||
|
||||
### Aliases
|
||||
|
||||
```graphql
|
||||
query CompareRatings($genre: String!) @auth(level: PUBLIC) {
|
||||
highRated: movies(where: { genre: { eq: $genre }, rating: { ge: 8 }}) {
|
||||
title rating
|
||||
}
|
||||
lowRated: movies(where: { genre: { eq: $genre }, rating: { lt: 5 }}) {
|
||||
title rating
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mutations
|
||||
|
||||
### Create
|
||||
|
||||
```graphql
|
||||
mutation CreateMovie($title: String!, $genre: String) @auth(level: USER) {
|
||||
movie_insert(data: {
|
||||
title: $title,
|
||||
genre: $genre
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Create with Server Values
|
||||
|
||||
```graphql
|
||||
mutation CreatePost($title: String!, $content: String!) @auth(level: USER) {
|
||||
post_insert(data: {
|
||||
authorUid_expr: "auth.uid", # Current user
|
||||
id_expr: "uuidV4()", # Auto-generate UUID
|
||||
createdAt_expr: "request.time", # Server timestamp
|
||||
title: $title,
|
||||
content: $content
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Update
|
||||
|
||||
```graphql
|
||||
mutation UpdateMovie($id: UUID!, $title: String, $genre: String) @auth(level: USER) {
|
||||
movie_update(
|
||||
id: $id,
|
||||
data: {
|
||||
title: $title,
|
||||
genre: $genre,
|
||||
updatedAt_expr: "request.time"
|
||||
}
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Update Operators
|
||||
|
||||
```graphql
|
||||
mutation IncrementViews($id: UUID!) @auth(level: PUBLIC) {
|
||||
movie_update(id: $id, data: {
|
||||
viewCount_update: { inc: 1 }
|
||||
})
|
||||
}
|
||||
|
||||
mutation AddTag($id: UUID!, $tag: String!) @auth(level: USER) {
|
||||
movie_update(id: $id, data: {
|
||||
tags_update: { add: [$tag] } # add, remove, append, prepend
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
| Operator | Types | Description |
|
||||
|----------|-------|-------------|
|
||||
| `inc` | Int, Float, Date, Timestamp | Increment value |
|
||||
| `dec` | Int, Float, Date, Timestamp | Decrement value |
|
||||
| `add` | Lists | Add items if not present |
|
||||
| `remove` | Lists | Remove all matching items |
|
||||
| `append` | Lists | Append to end |
|
||||
| `prepend` | Lists | Prepend to start |
|
||||
|
||||
### Upsert
|
||||
|
||||
```graphql
|
||||
mutation UpsertUser($email: String!, $name: String!) @auth(level: USER) {
|
||||
user_upsert(data: {
|
||||
uid_expr: "auth.uid",
|
||||
email: $email,
|
||||
name: $name
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Delete
|
||||
|
||||
```graphql
|
||||
mutation DeleteMovie($id: UUID!) @auth(level: USER) {
|
||||
movie_delete(id: $id)
|
||||
}
|
||||
|
||||
mutation DeleteOldDrafts @auth(level: USER) {
|
||||
post_deleteMany(where: {
|
||||
status: { eq: "draft" },
|
||||
createdAt: { lt_time: { now: true, sub: { days: 30 }}}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Filtered Updates/Deletes (User-Owned)
|
||||
|
||||
```graphql
|
||||
mutation UpdateMyPost($id: UUID!, $content: String!) @auth(level: USER) {
|
||||
post_update(
|
||||
first: { where: {
|
||||
id: { eq: $id },
|
||||
authorUid: { eq_expr: "auth.uid" } # Only own posts
|
||||
}},
|
||||
data: { content: $content }
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Scalars
|
||||
|
||||
Key scalars (`Movie_Key`, `User_Key`) are auto-generated types representing primary keys:
|
||||
|
||||
```graphql
|
||||
# Using key scalar
|
||||
query GetMovie($key: Movie_Key!) @auth(level: PUBLIC) {
|
||||
movie(key: $key) { title }
|
||||
}
|
||||
|
||||
# Variable format
|
||||
# { "key": { "id": "uuid-here" } }
|
||||
|
||||
# Composite key
|
||||
# { "key": { "movieId": "...", "userId": "..." } }
|
||||
```
|
||||
|
||||
Key scalars are returned by mutations:
|
||||
|
||||
```graphql
|
||||
mutation CreateAndFetch($title: String!) @auth(level: USER) {
|
||||
key: movie_insert(data: { title: $title })
|
||||
# Returns: { "key": { "id": "generated-uuid" } }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Step Operations
|
||||
|
||||
### @transaction
|
||||
|
||||
Ensures atomicity - all steps succeed or all rollback:
|
||||
|
||||
```graphql
|
||||
mutation CreateUserWithProfile($name: String!, $bio: String!)
|
||||
@auth(level: USER)
|
||||
@transaction {
|
||||
# Step 1: Create user
|
||||
user_insert(data: {
|
||||
uid_expr: "auth.uid",
|
||||
name: $name
|
||||
})
|
||||
# Step 2: Create profile (uses response from step 1)
|
||||
userProfile_insert(data: {
|
||||
userId_expr: "response.user_insert.uid",
|
||||
bio: $bio
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Using response Binding
|
||||
|
||||
Access results from previous steps:
|
||||
|
||||
```graphql
|
||||
mutation CreateTodoWithItem($listName: String!, $itemText: String!)
|
||||
@auth(level: USER)
|
||||
@transaction {
|
||||
todoList_insert(data: {
|
||||
id_expr: "uuidV4()",
|
||||
name: $listName
|
||||
})
|
||||
todoItem_insert(data: {
|
||||
listId_expr: "response.todoList_insert.id", # From previous step
|
||||
text: $itemText
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Embedded Queries
|
||||
|
||||
Run queries within mutations for validation:
|
||||
|
||||
```graphql
|
||||
mutation AddToPublicList($listId: UUID!, $item: String!)
|
||||
@auth(level: USER)
|
||||
@transaction {
|
||||
# Step 1: Verify list exists and is public
|
||||
query @redact {
|
||||
todoList(id: $listId) @check(expr: "this != null", message: "List not found") {
|
||||
isPublic @check(expr: "this == true", message: "List is not public")
|
||||
}
|
||||
}
|
||||
# Step 2: Add item
|
||||
todoItem_insert(data: { listId: $listId, text: $item })
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user