Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation for ORM 6.2 #6567

Merged
merged 9 commits into from
Jan 7, 2025
Merged

Update documentation for ORM 6.2 #6567

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1f77dd2
Update documentation for ORM 6.2
jharrell Jan 3, 2025
316c52e
update omit preview feature info
jharrell Jan 3, 2025
4775c04
fix anchors
jharrell Jan 3, 2025
20b3d92
update type mappping for sqlite
nikolasburk Jan 6, 2025
0e7778c
update section about omit api
nikolasburk Jan 6, 2025
feabb19
update section about omit api
nikolasburk Jan 6, 2025
17f70b9
Merge branch 'main' into jharrell/orm-6-2-updated-docs
nikolasburk Jan 7, 2025
decbf27
Merge branch 'main' into jharrell/orm-6-2-updated-docs
nikolasburk Jan 7, 2025
505f07a
Merge branch 'main' into jharrell/orm-6-2-updated-docs
nikolasburk Jan 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion content/200-orm/050-overview/500-databases/500-sqlite.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,12 @@ The SQLite connector maps the [scalar types](/orm/prisma-schema/data-model/model
| `Float` | `REAL` |
| `Decimal` | `DECIMAL` |
| `DateTime` | `NUMERIC` |
| `Json` | Not supported |
| `Json` | \* |
| `Enum` | \* |
| `Bytes` | `BLOB` |

> \* As SQLite does not have native `JSON` or `ENUM` types, these are implemented via shims and consistency is maintained by Prisma ORM.
nikolasburk marked this conversation as resolved.
Show resolved Hide resolved

## Rounding errors on big numbers

SQLite is a loosely-typed database. If your Schema has a field of type `Int`, then Prisma ORM prevents you from inserting a value larger than an integer. However, nothing prevents the database from directly accepting a bigger number. These manually-inserted big numbers cause rounding errors when queried.
Expand Down
2 changes: 1 addition & 1 deletion content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ const users = await prisma.user.findFirst()
If you want to customize the result and have a different combination of fields returned, you can:

- Use [`select`](/orm/reference/prisma-client-reference#select) to return specific fields. You can also use a [nested `select`](/orm/prisma-client/queries/relation-queries#select-specific-fields-of-included-relations) by selecting relation fields.
- Use [`omit`](/orm/reference/prisma-client-reference#omit-preview) to exclude specific fields from the result. `omit` can be seen as the "opposite" to `select`.
- Use [`omit`](/orm/reference/prisma-client-reference#omit) to exclude specific fields from the result. `omit` can be seen as the "opposite" to `select`.
- Use [`include`](/orm/reference/prisma-client-reference#include) to additionally [include relations](/orm/prisma-client/queries/relation-queries#nested-reads).

In all cases, the query result will be statically typed, ensuring that you don't accidentally access any fields that you did not actually query from the database.
Expand Down
10 changes: 4 additions & 6 deletions content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ By default Prisma Client returns all fields from a model. You can use `select` t

:::info

As of Prisma ORM 5.16.0, excluding fields globally and locally is supported via the `omitApi` Preview feature.
As of Prisma ORM 6.2.0, excluding fields globally and locally is supported. From versions 5.16.0 through 6.1.0, you must use the `omitApi` Preview feature.

:::

## Excluding a field globally using `omit`

The following is a type-safe way to exclude a field globally using the [`omitApi` Preview feature](/orm/reference/preview-features):
The following is a type-safe way to exclude a field globally:

<TabbedContent code>

Expand All @@ -23,7 +23,6 @@ The following is a type-safe way to exclude a field globally using the [`omitApi
```prisma
generator client {
provider = "prisma-client-js"
previewFeatures = ["omitApi"]
}

model User {
Expand Down Expand Up @@ -60,7 +59,7 @@ const user = await prisma.user.findUnique({ where: { id: 1 } })

## Excluding a field locally using `omit`

The following is a type-safe way to exclude a field locally using the `omitApi` Preview feature:
The following is a type-safe way to exclude a field locally:

<TabbedContent code>

Expand All @@ -69,7 +68,6 @@ The following is a type-safe way to exclude a field locally using the `omitApi`
```prisma
generator client {
provider = "prisma-client-js"
previewFeatures = ["omitApi"]
}

model User {
Expand Down Expand Up @@ -180,7 +178,7 @@ Local omit (when an `omit` option is provided in a query) only applies to the qu

:::note

The `omitApi` Preview feature, released in Prisma ORM 5.13.0, is the preferred way of omitting fields from a query result. The ability to globally omit fields was added to the `omitApi` Preview feature in Prisma ORM 5.16.0. This documentation is still relevant for versions of Prisma ORM prior to 5.13.0.
The `omitApi` feature, released in Preview in Prisma ORM 5.13.0 and Generally Available in Prisma ORM 6.2.0, is the preferred way of omitting fields from a query result. This documentation is still relevant for versions of Prisma ORM prior to 5.13.0.

:::

Expand Down
5 changes: 0 additions & 5 deletions ...200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@ metaDescription: 'How to read, write, and filter by Json fields.'
tocDepth: 3
---

<TopBlock>

Use the [`Json`](/orm/reference/prisma-schema-reference#json) Prisma ORM field type to read, write, and perform basic filtering on JSON types in the underlying database. In the following example, the `User` model has an optional `Json` field named `extendedPetsData`:

```prisma highlight=6;normal
Expand Down Expand Up @@ -35,7 +33,6 @@ Example field value:
}
```

> **Note**: The `Json` field is only supported if the [underlying database](/orm/overview) has a corresponding JSON data type.

The `Json` field supports a few additional types, such as `string` and `boolean`. These additional types exist to match the types supported by [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse):

Expand All @@ -49,8 +46,6 @@ export declare type JsonValue =
| JsonArray
```

</TopBlock>

## Use cases for JSON fields

Reasons to store data as JSON rather than representing data as related models include:
Expand Down
2 changes: 1 addition & 1 deletion content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ await user.save()

## Using `omit` query option with `result` extension component

You can use the [`omit` (Preview) option](/orm/reference/prisma-client-reference#omit-preview) with [custom fields](#add-a-custom-field-to-query-results) and fields needed by custom fields.
You can use the [`omit` (Preview) option](/orm/reference/prisma-client-reference#omit) with [custom fields](#add-a-custom-field-to-query-results) and fields needed by custom fields.

### `omit` fields needed by custom fields from query result

Expand Down
24 changes: 7 additions & 17 deletions content/200-orm/500-reference/050-prisma-client-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -792,7 +792,7 @@ const user = await prisma.user.findMany({
| `data` | `XOR<UserCreateInput,` <br />`UserUncheckedCreateInput>` | **Yes** | Wraps all the model fields in a type so that they can be provided when creating new records. It also includes relation fields which lets you perform (transactional) nested inserts. Fields that are marked as optional or have default values in the datamodel are optional. |
| [`select`](#select) | `XOR<UserSelect, null>` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. |
| [`include`](#include) | `XOR<UserInclude, null>` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. |
| [`omit`](#omit-preview) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 |
| [`omit`](#omit) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 |
| `relationLoadStrategy` | `'join'` or `'query'` | No | **Default: `join`**. Specifies the [load strategy](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview) for a relation query. Only available in combination with `include` (or `select` on a relation field). In [Preview](/orm/more/releases#preview) since 5.9.0. |

#### Return type
Expand Down Expand Up @@ -899,7 +899,7 @@ prisma:query COMMIT
| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)). <br></br>Before version 4.5.0, this type only wraps _unique_ fields of a model. |
| [`select`](#select) | `XOR<UserSelect, null>` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. |
| [`include`](#include) | `XOR<UserInclude, null>` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. |
| [`omit`](#omit-preview) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0. |
| [`omit`](#omit) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0. |
| `relationLoadStrategy` | `'join'` or `'query'` | No | **Default: `join`**. Specifies the [load strategy](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview) for a relation query. Only available in combination with `include` (or `select` on a relation field). In [Preview](/orm/more/releases#preview) since 5.9.0. |

#### Return type
Expand Down Expand Up @@ -948,7 +948,7 @@ This section covers the usage of the `upsert()` operation. To learn about using
| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)). <br></br>Before version 4.5.0, this type only wraps _unique_ fields of a model. |
| [`select`](#select) | `XOR<UserSelect, null>` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. |
| [`include`](#include) | `XOR<UserInclude, null>` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. |
| [`omit`](#omit-preview) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 |
| [`omit`](#omit) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 |
| `relationLoadStrategy` | `'join'` or `'query'` | No | **Default: `join`**. Specifies the [load strategy](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview) for a relation query. Only available in combination with `include` (or `select` on a relation field). In [Preview](/orm/more/releases#preview) since 5.9.0. |

#### Return type
Expand Down Expand Up @@ -1154,7 +1154,7 @@ To delete records that match a certain criteria, use [`deleteMany`](#deletemany)
| `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)). <br></br>Before version 4.5.0, this type only wraps _unique_ fields of a model. |
| [`select`](#select) | `XOR<UserSelect, null>` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. |
| [`include`](#include) | `XOR<UserInclude, null>` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. |
| [`omit`](#omit-preview) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 |
| [`omit`](#omit) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 |
| `relationLoadStrategy` | `'join'` or `'query'` | No | **Default: `join`**. Specifies the [load strategy](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview) for a relation query. Only available in combination with `include` (or `select` on a relation field). In [Preview](/orm/more/releases#preview) since 5.9.0. |

#### Return type
Expand Down Expand Up @@ -1265,7 +1265,7 @@ const users = await prisma.user.createMany({
| ----------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | `Enumerable<UserCreateManyInput>` | **Yes** | Wraps all the model fields in a type so that they can be provided when creating new records. Fields that are marked as optional or have default values in the datamodel are optional. |
| [`select`](#select) | `XOR<UserSelect, null>` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned objects. |
| [`omit`](#omit-preview) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned objects. In [Preview](/orm/more/releases#preview) since 5.13.0. Mutually exclusive with `select`. |
| [`omit`](#omit) | `XOR<UserOmit, null>` | No | Specifies which properties to exclude on the returned objects. In [Preview](/orm/more/releases#preview) since 5.13.0. Mutually exclusive with `select`. |
| [`include`](#include) | `XOR<UserInclude, null>` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned objects. |
| `skipDuplicates?` | `boolean` | No | Do not insert records with unique fields or ID fields that already exist. Only supported by databases that support [`ON CONFLICT DO NOTHING`](https://www.postgresql.org/docs/9.5/sql-insert.html#SQL-ON-CONFLICT). This excludes MongoDB and SQLServer |

Expand Down Expand Up @@ -1932,24 +1932,14 @@ const usersWithCount = await prisma.user.findMany({
</cmdResult>
</CodeWithResult>

### `omit` (Preview)
### `omit`

`omit` defines which fields are excluded in the object that Prisma Client returns.

Because the `omit` option is currently in Preview, you need to enable it via the `omitApi` preview feature flag in your Prisma schema file:

```prisma
generator client {
provider = "prisma-client-js"
previewFeatures = ["omitApi"]
}
```

After adding this flag, you need to run `prisma generate` again to re-generate Prisma Client.

#### Remarks

- You cannot combine `omit` and `select` since they serve opposite purposes
- `omit` was released into General Availability with Prisma ORM 6.2.0. It was available via the `omitApi` [Preview feature](/orm/reference/preview-features/client-preview-features) in Prisma ORM versions `5.13.0` through `6.1.0`.

#### Examples

Expand Down
2 changes: 1 addition & 1 deletion content/200-orm/500-reference/100-prisma-schema-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3357,7 +3357,7 @@ Defines an [enum](/orm/prisma-schema/data-model/models#defining-enums) .
### Remarks

- Enums are natively supported by [PostgreSQL](https://www.postgresql.org/docs/current/datatype-enum.html) and [MySQL](https://dev.mysql.com/doc/refman/8.0/en/enum.html)
- Enums are implemented and enforced at Prisma ORM level in MongoDB
- Enums are implemented and enforced at Prisma ORM level in SQLite and MongoDB

### Naming conventions

Expand Down
Loading
Loading