@xata.io/client 0.16.1 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @xata.io/client
 
+## 0.17.1
+
+### Patch Changes
+
+- [#584](https://github.com/xataio/client-ts/pull/584) [`a305072`](https://github.com/xataio/client-ts/commit/a3050726517632b4975f2a2ed5f771dd247e51d5) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix issues with multiple filters
+
+* [#249](https://github.com/xataio/client-ts/pull/249) [`7812a41`](https://github.com/xataio/client-ts/commit/7812a414b7d99e9515c0ce48a61ad7a8b84d65d0) Thanks [@xata-bot](https://github.com/xata-bot)! - API: Add first endpoints for migration requests and schema compare
+
+- [#585](https://github.com/xataio/client-ts/pull/585) [`d4a8ced`](https://github.com/xataio/client-ts/commit/d4a8ced9c257058ed7f660e01ee5fd1da154c391) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix problem with some special characters not being URI encoded
+
+* [#574](https://github.com/xataio/client-ts/pull/574) [`cf85b13`](https://github.com/xataio/client-ts/commit/cf85b13e1ca69e79100fd02f58d79d556012395d) Thanks [@SferaDev](https://github.com/SferaDev)! - Do not allow unknown tables on codegen output
+
+- [#576](https://github.com/xataio/client-ts/pull/576) [`2350739`](https://github.com/xataio/client-ts/commit/2350739d3f0a176b0f1fc77b0f4f597321349726) Thanks [@SferaDev](https://github.com/SferaDev)! - Allow sending empty, undefined or conditional filters
+
+* [#581](https://github.com/xataio/client-ts/pull/581) [`a336e61`](https://github.com/xataio/client-ts/commit/a336e6161be04a652e6f0f0a4c2edac10d50c99e) Thanks [@SferaDev](https://github.com/SferaDev)! - Update error codes in tracing
+
+## 0.17.0
+
+### Minor Changes
+
+- [#563](https://github.com/xataio/client-ts/pull/563) [`26e91d1`](https://github.com/xataio/client-ts/commit/26e91d1d84df082dedd7159271fc7c27ec87fefe) Thanks [@SferaDev](https://github.com/SferaDev)! - Return nulls on operations that can fail
+
+* [#563](https://github.com/xataio/client-ts/pull/563) [`3332d43`](https://github.com/xataio/client-ts/commit/3332d43121367f61c8d87dfb7da2af65bd1c278f) Thanks [@SferaDev](https://github.com/SferaDev)! - Return object on delete operation
+
+## 0.16.2
+
+### Patch Changes
+
+- [#541](https://github.com/xataio/client-ts/pull/541) [`c74467c`](https://github.com/xataio/client-ts/commit/c74467caeff4e3d60d0981a173b462e970c6c1fc) Thanks [@SferaDev](https://github.com/SferaDev)! - Add tracing with open telemetry
+
+* [#551](https://github.com/xataio/client-ts/pull/551) [`ee72bfe`](https://github.com/xataio/client-ts/commit/ee72bfef34765374ec66c7edaa6b5508c3f8e8dc) Thanks [@SferaDev](https://github.com/SferaDev)! - Fix filter operators and dates
+
+- [#552](https://github.com/xataio/client-ts/pull/552) [`e88effa`](https://github.com/xataio/client-ts/commit/e88effa00f8c2c0e24ec8cd60fb21859ac236191) Thanks [@SferaDev](https://github.com/SferaDev)! - Update error message for required settings
+
+* [#551](https://github.com/xataio/client-ts/pull/551) [`33293b3`](https://github.com/xataio/client-ts/commit/33293b3509d984bb9b1af457c96260d43f398efe) Thanks [@SferaDev](https://github.com/SferaDev)! - Add aliases for some operators
+
+- [#534](https://github.com/xataio/client-ts/pull/534) [`efc09b4`](https://github.com/xataio/client-ts/commit/efc09b420a25253b428662c2eec40ff3bc36ce79) Thanks [@SferaDev](https://github.com/SferaDev)! - Make sort direction optional
+
 ## 0.16.1
 
 ### Patch Changes

package/README.md

@@ -12,11 +12,11 @@ This SDK has zero dependencies, so it can be used in many JavaScript runtimes in
   - [Schema-generated Client](#schema-generated-client)
   - [Schema-less Client](#schema-less-client)
   - [API Design](#api-design)
-    - [Creating Objects](#creating-objects)
-    - [Query a Single Object by its ID](#query-a-single-object-by-its-id)
-    - [Querying Multiple Objects](#querying-multiple-objects)
-    - [Updating Objects](#updating-objects)
-    - [Deleting Objects](#deleting-objects)
+    - [Creating Records](#creating-records)
+    - [Query a Single Record by its ID](#query-a-single-record-by-its-id)
+    - [Querying Multiple Records](#querying-multiple-records)
+    - [Updating Records](#updating-records)
+    - [Deleting Records](#deleting-records)
   - [API Client](#api-client)
 - [Deno support](#deno-support)
 
@@ -102,7 +102,7 @@ The Xata SDK to create/read/update/delete records follows the [repository patter
 
 For example if you have a `users` table, there'll be a repository at `xata.db.users`. If you're using the schema-less client, you can also use the `xata.db.[table-name]` syntax to access the repository but without TypeScript auto-completion.
 
-#### Creating Objects
+#### Creating Records
 
 Invoke the `create()` method in the repository. Example:
 
@@ -123,22 +123,22 @@ const user = await xata.db.users.insert('user_admin', {
 And if you want to create or insert a record with a specific ID, you can invoke `updateOrInsert()`.
 
 ```ts
-const user = await client.db.users.updateOrInsert('user_admin', {
+const user = await xata.db.users.updateOrInsert('user_admin', {
   fullName: 'John Smith'
 });
 ```
 
-#### Query a Single Object by its ID
+#### Query a Single Record by its ID
 
 ```ts
-// `user` will be null if the object cannot be found
+// `user` will be null if the record cannot be found
 const user = await xata.db.users.read('rec_1234abcdef');
 ```
 
-#### Querying Multiple Objects
+#### Querying Multiple Records
 
 ```ts
-// Query objects selecting all fields.
+// Query records selecting all fields.
 const page = await xata.db.users.select().getPaginated();
 const user = await xata.db.users.select().getFirst();
 
@@ -146,7 +146,7 @@ const user = await xata.db.users.select().getFirst();
 const page = await xata.db.users.getPaginated();
 const user = await xata.db.users.getFirst();
 
-// Query objects selecting just one or more fields
+// Query records selecting just one or more fields
 const page = await xata.db.users.select('email', 'profile').getPaginated();
 
 // Apply constraints
@@ -158,6 +158,8 @@ const page = await xata.db.users.sort('full_name', 'asc').getPaginated();
 
 Query operations (`select()`, `filter()`, `sort()`) return a `Query` object. These objects are immutable. You can add additional constraints, `sort`, etc. by calling their methods, and a new query will be returned. In order to finally make a query to the database you'll invoke `getPaginated()`, `getMany()`, `getAll()`, or `getFirst()`.
 
+To learn the differences between these methods, see the [reference](https://docs.xata.io/sdk/reference#query).
+
 ```ts
 // Operators that combine multiple conditions can be deconstructed
 const { filter, any, all, not, sort } = xata.db.users;
@@ -205,9 +207,9 @@ for await (const records of xata.db.users.getIterator({ batchSize: 100 })) {
 }
 ```
 
-#### Updating Objects
+#### Updating Records
 
-Updating an object leaves the existing instance unchanged, but returns a new object with the updated values.
+Updating a record leaves the existing object unchanged, but returns a new object with the updated values.
 
 ```ts
 // Using an existing object
@@ -215,19 +217,19 @@ const updatedUser = await user.update({
   fullName: 'John Smith Jr.'
 });
 
-// Using an object's id
+// Using a record id
 const updatedUser = await xata.db.users.update('rec_1234abcdef', {
   fullName: 'John Smith Jr.'
 });
 ```
 
-#### Deleting Objects
+#### Deleting Records
 
 ```ts
 // Using an existing object
 await user.delete();
 
-// Using an object's id
+// Using a record id
 await xata.db.users.delete('rec_1234abcdef');
 ```
 
@@ -244,22 +246,22 @@ const api = new XataApiClient({ apiKey: process.env.XATA_API_KEY });
 Once you have initialized the API client, the operations are organized following the same hiearchy as in the [official documentation](https://docs.xata.io). You have different namespaces for each entity (ie. `workspaces`, `databases`, `tables`, `branches`, `users`, `records`...).
 
 ```ts
-const { id: workspace } = await client.workspaces.createWorkspace({ name: 'example', slug: 'example' });
-const { databaseName } = await client.databases.createDatabase(workspace, 'database');
+const { id: workspace } = await api.workspaces.createWorkspace({ name: 'example', slug: 'example' });
+const { databaseName } = await api.databases.createDatabase(workspace, 'database');
 
-await client.branches.createBranch(workspace, databaseName, 'branch');
-await client.tables.createTable(workspace, databaseName, 'branch', 'table');
-await client.tables.setTableSchema(workspace, databaseName, 'branch', 'table', {
+await api.branches.createBranch(workspace, databaseName, 'branch');
+await api.tables.createTable(workspace, databaseName, 'branch', 'table');
+await api.tables.setTableSchema(workspace, databaseName, 'branch', 'table', {
   columns: [{ name: 'email', type: 'string' }]
 });
 
-const { id: recordId } = await client.records.insertRecord(workspace, databaseName, 'branch', 'table', {
+const { id: recordId } = await api.records.insertRecord(workspace, databaseName, 'branch', 'table', {
   email: 'example@foo.bar'
 });
 
-const record = await client.records.getRecord(workspace, databaseName, 'branch', 'table', recordId);
+const record = await api.records.getRecord(workspace, databaseName, 'branch', 'table', recordId);
 
-await client.workspaces.deleteWorkspace(workspace);
+await api.workspaces.deleteWorkspace(workspace);
 ```
 
 ## Deno support

package/Usage.md

@@ -38,8 +38,29 @@ To get a collection of records, you can use the `Query` object. It provides the
 
 - `getFirst()`: returns the first record in the query results.
 - `getPaginated()`: returns a page of records in the query results.
-- `getAll()`: returns all the records in the query results.
-- `getMany()`: returns an array of some records in the query results.
+- `getAll()`: returns all the records in the query results by making multiple requests to iterate over all the pages which exist. If the query is not filtered and the table is a large dataset, this operation can affect the performance.
+- `getMany()`: returns an array with a subset of the first results in the query. The default [pagination](#page) size (20) is used and can be customised by passing a different `{ pagination: { size: number } }` in its options. To learn more about default values, see [helper variables](#helper-variables).
+
+All these methods allow customising its filters, column selection, column ordering, pagination or cache TTL. For example:
+
+```ts
+// First item sorting by name
+const user = await xata.db.users.getFirst({ sort: 'name' });
+
+// Get first 50 items but ignore the first one
+const users = await xata.db.users.getMany({ pagination: { size: 50, offset: 1 } });
+
+// Get page of 100 items where name contains "foo"
+const page = await xata.db.users.getPaginated({ filter: { name: { $contains: 'foo' } }, pagination: { size: 100 } });
+
+// Get all admin users and cache the result for 5 minutes
+const user = await xata.db.users.filter('role', 'admin').getAll({ cache: 5 * 60 * 1000 });
+
+// Overwrite values set in a query
+const query = xata.db.users.filter('role', 'admin').select(['name']);
+const adminUsers = await query.getAll();
+const firstAdminUserWithEmail = await query.getFirst({ columns: ['name', 'email'] });
+```
 
 Since the [`Repository`](#repository) class implements the `Query` interface, you can use it to query and paginate the records in the table too.
 
@@ -375,10 +396,10 @@ for await (const users of xata.db.users.getIterator({ batchSize: 50 })) {
 
 We expose some helper variables of the API limits when paginating:
 
-- `PAGINATION_MAX_SIZE`: Maximum page size.
-- `PAGINATION_DEFAULT_SIZE`: Default page size.
-- `PAGINATION_MAX_OFFSET`: Maximum offset.
-- `PAGINATION_DEFAULT_OFFSET`: Default offset.
+- `PAGINATION_MAX_SIZE`: Maximum page size (200).
+- `PAGINATION_DEFAULT_SIZE`: Default page size (20).
+- `PAGINATION_MAX_OFFSET`: Maximum offset (800).
+- `PAGINATION_DEFAULT_OFFSET`: Default offset (0).
 
 You can use these variables if you implement your own pagination mechanism, as they will be updated when our API limits are updated.