@xata.io/client 0.15.0 → 0.16.2

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @xata.io/client
 
+## 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
+
+- [#531](https://github.com/xataio/client-ts/pull/531) [`e33d8fb`](https://github.com/xataio/client-ts/commit/e33d8fbca264d3ab1597ed698d5e79484dcba8a3) Thanks [@xata-bot](https://github.com/xata-bot)! - Add new method to list database metadata in the API client
+
+* [#524](https://github.com/xataio/client-ts/pull/524) [`a3b1044`](https://github.com/xataio/client-ts/commit/a3b1044038c4ae73b4aacaa112818e69b7d380e1) Thanks [@SferaDev](https://github.com/SferaDev)! - Expose internal config information
+
+- [#525](https://github.com/xataio/client-ts/pull/525) [`5f0f2c2`](https://github.com/xataio/client-ts/commit/5f0f2c2bb42da360e810f0a61ce360f8f8b07a04) Thanks [@xata-bot](https://github.com/xata-bot)! - Update dependencies
+
+## 0.16.0
+
+### Minor Changes
+
+- [#485](https://github.com/xataio/client-ts/pull/485) [`a9cbb26`](https://github.com/xataio/client-ts/commit/a9cbb263fbca47cb91a827db252d95a5bb4079a6) Thanks [@SferaDev](https://github.com/SferaDev)! - Allow selecting columns with record operations
+
+* [#485](https://github.com/xataio/client-ts/pull/485) [`7e04a3d`](https://github.com/xataio/client-ts/commit/7e04a3d1c51958a44f687a0036ead8bb3f5a2dfb) Thanks [@SferaDev](https://github.com/SferaDev)! - Remove record cache
+
+### Patch Changes
+
+- [#503](https://github.com/xataio/client-ts/pull/503) [`6a96ea5`](https://github.com/xataio/client-ts/commit/6a96ea5da4c5b7ca9a99b57ebbce8d6766b5d4d8) Thanks [@xata-bot](https://github.com/xata-bot)! - Update API response types for create of tables and branches
+
+* [#421](https://github.com/xataio/client-ts/pull/421) [`43f2560`](https://github.com/xataio/client-ts/commit/43f25605ddd0d2fd514a1542a14389d28955c500) Thanks [@SferaDev](https://github.com/SferaDev)! - Add search boosters and allow prefix search
+
 ## 0.15.0
 
 ### Patch Changes

package/README.md

@@ -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;

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.
 
@@ -155,6 +176,13 @@ const user = await xata.db.users.read(object1);
 const users = await xata.db.users.read([object1, object2]);
 ```
 
+By default an object with the first level properties is returned. If you want to reduce or expand its columns, you can pass an array of columns to the `read()` method.
+
+```ts
+const user = await xata.db.users.read('rec_1234abcdef', ['fullName', 'team.name']);
+const users = await xata.db.users.read(['rec_1234abcdef', 'rec_5678defgh'], ['fullName', 'team.name']);
+```
+
 ### Creating Records
 
 Both the `create()` and `createOrUpdate()` methods can be used to create a new record.
@@ -202,6 +230,19 @@ const users = await xata.db.users.createOrUpdate([
 ]);
 ```
 
+By default, the `create` and `createOrUpdate` methods will return the created record with the first level properties. If you want to reduce or expand its columns, you can pass an array of columns to the `create` or `createOrUpdate` method.
+
+```ts
+const user = await xata.db.users.create('user_admin', { fullName: 'John Smith' }, ['fullName', 'team.name']);
+const users = await xata.db.users.createOrUpdate(
+  [
+    { id: 'user_admin', fullName: 'John Smith' },
+    { id: 'user_manager', fullName: 'Jane Doe' }
+  ],
+  ['fullName', 'team.name']
+);
+```
+
 ### Updating records
 
 The `update()` method can be used to update an existing record. It will throw an `Error` if the record cannot be found.
@@ -225,6 +266,12 @@ const users = await xata.db.users.update([
 ]);
 ```
 
+By default, the `update` method will return the updated record with the first level properties. If you want to reduce or expand its columns, you can pass an array of columns to the `update` method.
+
+```ts
+const user = await xata.db.users.update('rec_1234abcdef', { fullName: 'John Smith' }, ['fullName', 'team.name']);
+```
+
 ### Deleting Records
 
 The `delete()` method can be used to delete an existing record. It will throw an `Error` if the record cannot be found.
@@ -349,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.
 
@@ -373,6 +420,13 @@ user?.update({ fullName: 'John Doe' }); // Partially updates the record
 user?.delete(); // Deletes the record
 ```
 
+The `read` and `update` methods return the updated record with the first level properties. If you want to reduce or expand its columns, you can pass an array of columns to the `read` and `update` methods.
+
+```ts
+const user = await xata.db.users.read('rec_1234abcdef');
+user?.read(['fullName', 'team.name']); // Reads the record again with the `fullName` and `team.name` columns
+```
+
 If the table contains a link property, it will be represented as a `Link` object containing its `id` property and methods to read again or update the linked record.
 
 ```ts