add bring your own ID docs

prisma · Nov 14, 2019 · c6ba8fd · c6ba8fd
1 parent 474c503
commit c6ba8fd
Showing 1 changed file with 50 additions and 26 deletions.
diff --git a/docs/photon/api.md b/docs/photon/api.md
@@ -7,6 +7,7 @@ Photon is a type-safe database client auto-generated based on your [data model d
 - [Field selection](#field-selection)
 - [Relations](#relations)
 - [Raw databases access](#raw-database-access)
+- [Bring your own ID](#bring-your-own-id)
 - [API Reference](#api-reference)
 - [Filtering](#filtering)
 - [Debugging](#debugging)
@@ -142,6 +143,29 @@ Coming soon.
 
 Learn more about relations in the generated Photon API [here](../relations.md#relations-in-the-generated-Photon-API).
 
+## Bring your own ID
+
+With Photon.js, you can set your own values for fields that are annotated with the `@id` attribute. This attribute express that the respective field is considered a _primary key_. Consider the following model:
+
+```groovy
+model User {
+  id    Int    @id
+  name  String
+}
+```
+
+You can provide the `id` as input value in [`create`](#create) and [`update`](#update) operations, for example:
+
+```ts
+const user = await photon.users.create({
+  data: {
+    id: 1
+  }
+})
+```
+
+Note that Photon.js will throw an error if you're trying to create/update a record with an `id` value that already belongs to another record since the `@id` attribute always implies _uniqueness_.
+
 ## Raw database access
 
 Coming soon.
@@ -156,9 +180,9 @@ Creates a new `Photon` instance.
 
 #### Options
 
-| Name          | Type          | Required | Description                                                                                                                                                                                       |
-| ------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debug`       | `boolean`     | No       | When set to `true`, the `Photon` instance prints additional logging output to the console when sending requests to Prisma's query engine. **Default**: `false`.                                   |
+| Name          | Type          | Required | Description                                                                                                                                                                                                                         |
+| ------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debug`       | `boolean`     | No       | When set to `true`, the `Photon` instance prints additional logging output to the console when sending requests to Prisma's query engine. **Default**: `false`.                                                                     |
 | `datasources` | `Datasources` | No       | Lets you override the connection string for a data source. The keys of the `datasources` object are autogenerated and correspond to the names to the data sources specified in your [Prisma schema file](../prisma-schema-file.md). |
 
 #### Examples
@@ -339,7 +363,7 @@ The Photon.js API offers filtering options for constraining the items that are r
 
 The following examples are based on this data model:
 
-```
+```groovy
 model User {
   id     Int    @id
   name   String
@@ -354,22 +378,22 @@ enum Role {
 }
 ```
 
-Filtering can be applied to this data model.  It is not the same as manipulating the selection set.  Based on the `User` model, Photon generates the `UserWhereInput` type, which holds the filtering properties.  
+Filtering can be applied to this data model. It is not the same as manipulating the selection set. Based on the `User` model, Photon generates the `UserWhereInput` type, which holds the filtering properties.
 
 ```ts
 export declare type UserWhereInput = {
-    id?: number | IntFilter | null;
-    name?: string | StringFilter | null;
-    email?: string | StringFilter | null;
-    role?: Role | RoleFilter | null;
-    active?: boolean | BooleanFilter | null;
-    AND?: Enumerable<UserWhereInput>;
-    OR?: Enumerable<UserWhereInput>;
-    NOT?: Enumerable<UserWhereInput>;
-};
+  id?: number | IntFilter | null
+  name?: string | StringFilter | null
+  email?: string | StringFilter | null
+  role?: Role | RoleFilter | null
+  active?: boolean | BooleanFilter | null
+  AND?: Enumerable<UserWhereInput>
+  OR?: Enumerable<UserWhereInput>
+  NOT?: Enumerable<UserWhereInput>
+}
 ```
 
-For example, to get the record for the user with the `id` 1, `where` is used in combination with the `id` `IntFilter`: 
+For example, to get the record for the user with the `id` 1, `where` is used in combination with the `id` `IntFilter`:
 
 ```ts
 const result = await photon.users.findMany({
@@ -386,13 +410,13 @@ const result = await photon.users.findMany({
 
 > Note: As a recap, the `findMany` API returns a list of objects which can be filtered by any model property.
 
-To get the record for the user with the `name` Alice with a USER `role`, `where` is used in combination with the `name` `StringFilter` and the `role` `RoleFilter`: 
+To get the record for the user with the `name` Alice with a USER `role`, `where` is used in combination with the `name` `StringFilter` and the `role` `RoleFilter`:
 
 ```ts
 const result = await photon.users.findMany({
-  where: { 
-    name: "Alice",
-    role: "USER",
+  where: {
+    name: 'Alice',
+    role: 'USER',
   },
 })
 // result = [{
@@ -404,15 +428,15 @@ const result = await photon.users.findMany({
 // }]
 ```
 
-To apply one of the operator filters (AND, OR, NOT), filter for the record where the user with the `name` Alice has a non-active status. Here, `where` is used in combination with the `name` `StringFilter`, the `active` `BooleanFilter`, and the `NOT` operator: 
+To apply one of the operator filters (`AND`, `OR`, `NOT`), filter for the record where the user with the `name` Alice has a non-active status. Here, `where` is used in combination with the `name` `StringFilter`, the `active` `BooleanFilter`, and the `NOT` operator:
 
 ```ts
 const result = await photon.users.findMany({
-  where: { 
-    name: "Alice",
-    NOT:{
-      active: true
-    } 
+  where: {
+    name: 'Alice',
+    NOT: {
+      active: true,
+    },
   },
 })
 // result = {
@@ -435,7 +459,7 @@ Photon connects and disconnects from your data sources using the following two m
 - `connect(): Promise<void>`
 - `disconnect(): Promise<void>`
 
-Unless you want to employ a specific optimization, calling `photon.connect()` is not necessary thanks to the _lazy connect_ behavior: The `Photon` instance connects lazily when the first request is made to the API (`connect()` is called for you under the hood). 
+Unless you want to employ a specific optimization, calling `photon.connect()` is not necessary thanks to the _lazy connect_ behavior: The `Photon` instance connects lazily when the first request is made to the API (`connect()` is called for you under the hood).
 
 If you need the first request to respond instantly and can't wait for the lazy connection to be established, you can explicitly call `photon.connect()` to establish a connection to the data source.