@supabase/postgrest-js 3.0.0-next.17 → 3.0.0-next.18

package/dist/index.d.cts

@@ -2876,35 +2876,350 @@ declare class PostgrestQueryBuilder<ClientOptions extends ClientServerOptions, S
     head?: boolean;
     count?: 'exact' | 'planned' | 'estimated' | (string & {});
   }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], ResultOne[], RelationName, Relationships, 'GET'>;
+  /**
+   * Perform an INSERT into the table or view.
+   *
+   * By default, inserted rows are not returned. To return it, chain the call
+   * with `.select()`.
+   *
+   * @param values - The values to insert. Pass an object to insert a single row
+   * or an array to insert multiple rows.
+   *
+   * @param options - Named parameters
+   *
+   * @param options.count - Count algorithm to use to count inserted rows.
+   *
+   * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+   * hood.
+   *
+   * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+   * statistics under the hood.
+   *
+   * `"estimated"`: Uses exact count for low numbers and planned count for high
+   * numbers.
+   *
+   * @param options.defaultToNull - Make missing fields default to `null`.
+   * Otherwise, use the default value for the column. Only applies for bulk
+   * inserts.
+   *
+   * @category Database
+   *
+   * @example Create a record
+   * ```ts
+   * const { error } = await supabase
+   *   .from('countries')
+   *   .insert({ id: 1, name: 'Mordor' })
+   * ```
+   *
+   * @exampleSql Create a record
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   * ```
+   *
+   * @exampleResponse Create a record
+   * ```json
+   * {
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
+   *
+   * @example Create a record and return it
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('countries')
+   *   .insert({ id: 1, name: 'Mordor' })
+   *   .select()
+   * ```
+   *
+   * @exampleSql Create a record and return it
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   * ```
+   *
+   * @exampleResponse Create a record and return it
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "Mordor"
+   *     }
+   *   ],
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
+   *
+   * @exampleDescription Bulk create
+   * A bulk create operation is handled in a single transaction.
+   * If any of the inserts fail, none of the rows are inserted.
+   *
+   * @example Bulk create
+   * ```ts
+   * const { error } = await supabase
+   *   .from('countries')
+   *   .insert([
+   *     { id: 1, name: 'Mordor' },
+   *     { id: 1, name: 'The Shire' },
+   *   ])
+   * ```
+   *
+   * @exampleSql Bulk create
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   * ```
+   *
+   * @exampleResponse Bulk create
+   * ```json
+   * {
+   *   "error": {
+   *     "code": "23505",
+   *     "details": "Key (id)=(1) already exists.",
+   *     "hint": null,
+   *     "message": "duplicate key value violates unique constraint \"countries_pkey\""
+   *   },
+   *   "status": 409,
+   *   "statusText": "Conflict"
+   * }
+   * ```
+   */
   insert<Row extends (Relation$1 extends {
     Insert: unknown;
   } ? Relation$1['Insert'] : never)>(values: RejectExcessProperties<Relation$1 extends {
     Insert: unknown;
-  } ? Relation$1['Insert'] : never, Row>, options?: {
-    count?: 'exact' | 'planned' | 'estimated' | (string & {});
-  }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'POST'>;
-  insert<Row extends (Relation$1 extends {
+  } ? Relation$1['Insert'] : never, Row> | RejectExcessProperties<Relation$1 extends {
     Insert: unknown;
-  } ? Relation$1['Insert'] : never)>(values: RejectExcessProperties<Relation$1 extends {
-    Insert: unknown;
-  } ? Relation$1['Insert'] : never, Row>[], options?: {
+  } ? Relation$1['Insert'] : never, Row>[], {
+    count,
+    defaultToNull
+  }?: {
     count?: 'exact' | 'planned' | 'estimated' | (string & {});
     defaultToNull?: boolean;
   }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'POST'>;
+  /**
+   * Perform an UPSERT on the table or view. Depending on the column(s) passed
+   * to `onConflict`, `.upsert()` allows you to perform the equivalent of
+   * `.insert()` if a row with the corresponding `onConflict` columns doesn't
+   * exist, or if it does exist, perform an alternative action depending on
+   * `ignoreDuplicates`.
+   *
+   * By default, upserted rows are not returned. To return it, chain the call
+   * with `.select()`.
+   *
+   * @param values - The values to upsert with. Pass an object to upsert a
+   * single row or an array to upsert multiple rows.
+   *
+   * @param options - Named parameters
+   *
+   * @param options.onConflict - Comma-separated UNIQUE column(s) to specify how
+   * duplicate rows are determined. Two rows are duplicates if all the
+   * `onConflict` columns are equal.
+   *
+   * @param options.ignoreDuplicates - If `true`, duplicate rows are ignored. If
+   * `false`, duplicate rows are merged with existing rows.
+   *
+   * @param options.count - Count algorithm to use to count upserted rows.
+   *
+   * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+   * hood.
+   *
+   * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+   * statistics under the hood.
+   *
+   * `"estimated"`: Uses exact count for low numbers and planned count for high
+   * numbers.
+   *
+   * @param options.defaultToNull - Make missing fields default to `null`.
+   * Otherwise, use the default value for the column. This only applies when
+   * inserting new rows, not when merging with existing rows under
+   * `ignoreDuplicates: false`. This also only applies when doing bulk upserts.
+   *
+   * @example Upsert a single row using a unique key
+   * ```ts
+   * // Upserting a single row, overwriting based on the 'username' unique column
+   * const { data, error } = await supabase
+   *   .from('users')
+   *   .upsert({ username: 'supabot' }, { onConflict: 'username' })
+   *
+   * // Example response:
+   * // {
+   * //   data: [
+   * //     { id: 4, message: 'bar', username: 'supabot' }
+   * //   ],
+   * //   error: null
+   * // }
+   * ```
+   *
+   * @example Upsert with conflict resolution and exact row counting
+   * ```ts
+   * // Upserting and returning exact count
+   * const { data, error, count } = await supabase
+   *   .from('users')
+   *   .upsert(
+   *     {
+   *       id: 3,
+   *       message: 'foo',
+   *       username: 'supabot'
+   *     },
+   *     {
+   *       onConflict: 'username',
+   *       count: 'exact'
+   *     }
+   *   )
+   *
+   * // Example response:
+   * // {
+   * //   data: [
+   * //     {
+   * //       id: 42,
+   * //       handle: "saoirse",
+   * //       display_name: "Saoirse"
+   * //     }
+   * //   ],
+   * //   count: 1,
+   * //   error: null
+   * // }
+   * ```
+   *
+   * @category Database
+   *
+   * @remarks
+   * - Primary keys must be included in `values` to use upsert.
+   *
+   * @example Upsert your data
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('instruments')
+   *   .upsert({ id: 1, name: 'piano' })
+   *   .select()
+   * ```
+   *
+   * @exampleSql Upsert your data
+   * ```sql
+   * create table
+   *   instruments (id int8 primary key, name text);
+   *
+   * insert into
+   *   instruments (id, name)
+   * values
+   *   (1, 'harpsichord');
+   * ```
+   *
+   * @exampleResponse Upsert your data
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "piano"
+   *     }
+   *   ],
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
+   *
+   * @example Bulk Upsert your data
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('instruments')
+   *   .upsert([
+   *     { id: 1, name: 'piano' },
+   *     { id: 2, name: 'harp' },
+   *   ])
+   *   .select()
+   * ```
+   *
+   * @exampleSql Bulk Upsert your data
+   * ```sql
+   * create table
+   *   instruments (id int8 primary key, name text);
+   *
+   * insert into
+   *   instruments (id, name)
+   * values
+   *   (1, 'harpsichord');
+   * ```
+   *
+   * @exampleResponse Bulk Upsert your data
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "piano"
+   *     },
+   *     {
+   *       "id": 2,
+   *       "name": "harp"
+   *     }
+   *   ],
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
+   *
+   * @exampleDescription Upserting into tables with constraints
+   * In the following query, `upsert()` implicitly uses the `id`
+   * (primary key) column to determine conflicts. If there is no existing
+   * row with the same `id`, `upsert()` inserts a new row, which
+   * will fail in this case as there is already a row with `handle` `"saoirse"`.
+   * Using the `onConflict` option, you can instruct `upsert()` to use
+   * another column with a unique constraint to determine conflicts.
+   *
+   * @example Upserting into tables with constraints
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('users')
+   *   .upsert({ id: 42, handle: 'saoirse', display_name: 'Saoirse' })
+   *   .select()
+   * ```
+   *
+   * @exampleSql Upserting into tables with constraints
+   * ```sql
+   * create table
+   *   users (
+   *     id int8 generated by default as identity primary key,
+   *     handle text not null unique,
+   *     display_name text
+   *   );
+   *
+   * insert into
+   *   users (id, handle, display_name)
+   * values
+   *   (1, 'saoirse', null);
+   * ```
+   *
+   * @exampleResponse Upserting into tables with constraints
+   * ```json
+   * {
+   *   "error": {
+   *     "code": "23505",
+   *     "details": "Key (handle)=(saoirse) already exists.",
+   *     "hint": null,
+   *     "message": "duplicate key value violates unique constraint \"users_handle_key\""
+   *   },
+   *   "status": 409,
+   *   "statusText": "Conflict"
+   * }
+   * ```
+   */
   upsert<Row extends (Relation$1 extends {
     Insert: unknown;
   } ? Relation$1['Insert'] : never)>(values: RejectExcessProperties<Relation$1 extends {
     Insert: unknown;
-  } ? Relation$1['Insert'] : never, Row>, options?: {
-    onConflict?: string;
-    ignoreDuplicates?: boolean;
-    count?: 'exact' | 'planned' | 'estimated' | (string & {});
-  }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'POST'>;
-  upsert<Row extends (Relation$1 extends {
+  } ? Relation$1['Insert'] : never, Row> | RejectExcessProperties<Relation$1 extends {
     Insert: unknown;
-  } ? Relation$1['Insert'] : never)>(values: RejectExcessProperties<Relation$1 extends {
-    Insert: unknown;
-  } ? Relation$1['Insert'] : never, Row>[], options?: {
+  } ? Relation$1['Insert'] : never, Row>[], {
+    onConflict,
+    ignoreDuplicates,
+    count,
+    defaultToNull
+  }?: {
     onConflict?: string;
     ignoreDuplicates?: boolean;
     count?: 'exact' | 'planned' | 'estimated' | (string & {});