Adjust docs for column type updates (#377)

Adjust docs for UI changes: - string replaced by text - multiple replaced by text[] - datetime replaced by timestamptz - deprecation of email type --------- Co-authored-by: Emily Morgan <[email protected]> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
xataio · Aug 12, 2024 · e4ee1fe · e4ee1fe
1 parent b7d9a07
commit e4ee1fe
Show file tree

Hide file tree

Showing 6 changed files with 76 additions and 61 deletions.
diff --git a/030-Data-types/030-data-model.mdx b/030-Data-types/030-data-model.mdx
@@ -7,27 +7,27 @@ slug: concepts/data-model
 published: true
 ---
 
-Xata builds on top of Postgres and thus supports the [default data types](https://www.postgresql.org/docs/current/datatype.html) inherit in that platform. Xata additionally adds to that list with unique types such as `file`, `filearray` and `vector` to handle platform features like [file attachements](/docs/sdk/file-attachments) and [vector searching](/docs/sdk/vector-search). In addition, there are some added types to simplify validation of common types like `email` and `multiple`. Usage of these types is ultimately optional if you wish to use Xata only as a Postgres host. If you do decide to utilize them (which is the default way Xata operates through our UI), it is required that you interact with these types through the Xata SDKs.
+Xata builds on top of Postgres and thus supports the [default data types](https://www.postgresql.org/docs/current/datatype.html) inherit in that platform. Xata additionally adds to that list with unique types such as `xata_file` (file), `xata_file_array` (file[]) and `vector` to handle platform features like [file attachements](/docs/sdk/file-attachments) and [vector searching](/docs/sdk/vector-search). In addition, there are some added types to simplify validation of common types like `email` (deprecated) and `text[]` (`multiple`). Usage of these types is ultimately optional if you wish to use Xata only as a Postgres host. If you do decide to utilize them (which is the default way Xata operates through our UI), it is required that you interact with these types through the Xata SDKs.
 
 ## Xata specific data types
 
 Below is a mapping of the additional data types Xata provides alongside Postgres types.
 
-| Xata data type          | PostgreSQL data type | Notes                                                   |
-| ----------------------- | -------------------- | ------------------------------------------------------- |
-| [string](#string)       | text                 | With constraints on maximum length of 2048 characters   |
-| [text](#text)           | text                 | With constraints on maximum length of 204800 characters |
-| [int](#int)             | bigint               |                                                         |
-| [float](#float)         | double precision     |                                                         |
-| [datetime](#datetime)   | timestamptz          |                                                         |
-| [bool](#bool)           | boolean              |                                                         |
-| [email](#email)         | text                 | Validated by Xata                                       |
-| [multiple](#multiple)   | text[]               | Validated by Xata                                       |
-| [file](#file)           | xata.xata_file       | json object stored natively as jsonb                    |
-| [filearray](#filearray) | xata.xata_file_array | json array stored natively as jsonb                     |
-| [link](#link)           | foreign key          |                                                         |
-| [vector](#vector)       | real[]               |                                                         |
-| [json](#json)           | jsonb                |                                                         |
+| Xata data type                         | PostgreSQL data type | Notes                                                 |
+| -------------------------------------- | -------------------- | ----------------------------------------------------- |
+| [text](#text)                          | text                 |                                                       |
+| [string](#string) (deprecated)         | text                 | With constraints on maximum length of 2048 characters |
+| [int](#int)                            | bigint               |                                                       |
+| [float](#float)                        | double precision     |                                                       |
+| [timestamptz (datetime)](#timestamptz) | timestamptz          |                                                       |
+| [bool](#bool)                          | boolean              |                                                       |
+| [email](#email) (deprecated)           | text                 | Validated by Xata                                     |
+| [text[] (multiple)](#text[])           | text[]               | Validated by Xata                                     |
+| [xata_file](#xata_file)                | xata.xata_file       | json object stored natively as jsonb                  |
+| [xata_file_array](#xata_file_array)    | xata.xata_file_array | json array stored natively as jsonb                   |
+| [link](#link)                          | foreign key          |                                                       |
+| [vector](#vector)                      | real[]               |                                                       |
+| [json](#json)                          | jsonb                |                                                       |
 
 ## Limitations when using native Postgres types
 
@@ -57,7 +57,7 @@ Let's look at a JSON representation of a sample Xata schema to understand how it
       "columns": [
         {
           "name": "name",
-          "type": "string",
+          "type": "text",
           "unique": true
         },
         {
@@ -96,11 +96,11 @@ Let's look at a JSON representation of a sample Xata schema to understand how it
         },
         {
           "name": "full_name",
-          "type": "string"
+          "type": "text"
         },
         {
           "name": "address",
-          "type": "string"
+          "type": "text"
         },
         {
           "name": "team",
@@ -174,7 +174,7 @@ The keys in the JSON are the column names. The values are the data. The correspo
       "columns": [
         {
           "name": "name",
-          "type": "string"
+          "type": "text"
         },
         {
           "name": "email",
@@ -186,7 +186,7 @@ The keys in the JSON are the column names. The values are the data. The correspo
         },
         {
           "name": "address",
-          "type": "string"
+          "type": "text"
         },
         {
           "name": "labels",
@@ -205,29 +205,39 @@ In the above, it's worth noting:
 
 ## Column types
 
-### string
+### text
 
-The `string` type represents a simple string. The values of this type are indexed both for quick exact matching and for full-text search. Set `unique` to ensure the strings you insert are unique. Set `notNull` to require a value.
+The `text` type represents a string or a long-form text. If a value must be provided, you can use the `notNull` setting to enforce this requirement.
 
 Example definition:
 
 ```json
 {
-  "name": "name",
-  "type": "string"
+  "name": "address",
+  "type": "text"
 }
 ```
 
-### text
+<Alert status="warning">
+  Note: In the UI, uniqueness on text columns can only be enabled on Postgres-enabled databases. For "legacy" databases,
+  uniqueness can only be enabled via the CLI.
+</Alert>
 
-The `text` type represents a long-form text. Unlike the `string type`, `text` column values are indexed and optimized for efficient free-text searches, rather than exact matches. If a value must be provided, you can use the `notNull` setting to enforce this requirement.
+### string
+
+<Alert status="warning">
+  Note: The string type is deprecated. Existing string columns will continue working and can be created via the CLI but
+  this type is not available for new columns via the UI. Uniqueness can only be enabled via the CLI.
+</Alert>
+The `string` type represents a simple string. The values of this type are indexed both for quick exact matching and for full-text
+search. Set `unique` to ensure the strings you insert are unique. Set `notNull` to require a value.
 
 Example definition:
 
 ```json
 {
   "name": "address",
-  "type": "text"
+  "type": "string"
 }
 ```
 
@@ -257,9 +267,9 @@ Example definition:
 }
 ```
 
-### datetime
+### timestamptz
 
-The `datetime` type represents a point in time up to millisecond precision. It has the _date_ part and the _time_ part, and both are mandatory. A [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)-compliant `string` is used for input and output representation. Set `unique` to make sure the values you insert are unique. Set `notNull` so the column value cannot be empty. Select a default value using `defaultValue`. If you set `now` as the default value, the default value of the column will be the time when the record was inserted.
+The `timestamptz` (datetime) type represents a point in time up to millisecond precision. It has the _date_ part and the _time_ part, and both are mandatory. A [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)-compliant `string` is used for input and output representation. Set `unique` to make sure the values you insert are unique. Set `notNull` so the column value cannot be empty. Select a default value using `defaultValue`. If you set `now` as the default value, the default value of the column will be the time when the record was inserted.
 
 Example definition:
 
@@ -303,7 +313,12 @@ Example definition:
 
 ### email
 
-The `email` type represents an email address. Valid email addresses are not longer than 254 characters and respect this regular expression:
+<Alert status="warning">
+  Note: The email type is deprecated. Existing email columns will continue working and can be created via the CLI but
+  this type is not available for new columns via the UI.
+</Alert>
+The `email` type represents an email address. Valid email addresses are not longer than 254 characters and respect this regular
+expression:
 
 ```json
 ^[a-zA-Z0-9.!#$%&'*+\\/=?^_`{|}~-]+@
@@ -330,9 +345,9 @@ Example value:
 }
 ```
 
-### multiple
+### text[]
 
-The `multiple` type represents an array of strings.
+The `text[]` (multiple) type represents an array of strings.
 
 Example definition:
 
@@ -343,7 +358,7 @@ Example definition:
 }
 ```
 
-To insert a value into a `multiple` column, use a JSON array of strings, for example:
+To insert a value into a `text[]` (multiple) column, use a JSON array of strings, for example:
 
 ```json
 {
@@ -395,11 +410,11 @@ To insert the value for a `link` column, use the target record ID as the value.
 }
 ```
 
-### file
+### xata_file
 
-The `file` type is the representation of a file in the Xata database. For every file, the column stores JSON objects with a predefined schema. The file object is used to upload a file, retrieve its content, as well as update or query its metadata.
+The `xata_file` (`file`) type is the representation of a file in the Xata database. For every file, the column stores JSON objects with a predefined schema. The file object is used to upload a file, retrieve its content, as well as update or query its metadata.
 
-The file object consists of the following fields:
+The xata_file object consists of the following fields:
 
 - `name` refers to the file name.
 - `mediaType` follows the definition provided by RFC 6838. Xata may utilize it as a hint, but it does not validate the content against the declared media type. If the value is missing, the default is set to `application/octet-stream`.
@@ -420,7 +435,7 @@ All the fields above are input fields and can be used in insert or update reques
 }
 ```
 
-When reading or querying a file object, Xata adds a set of read only fields:
+When reading or querying a xata_file object, Xata adds a set of read only fields:
 
 - `size` - represents the file's size in bytes. It's important to note that this size refers to the original file, not the size of the base64 encoding.
 - `version` - keeps track of the updates made to the specific file.
@@ -429,7 +444,7 @@ When reading or querying a file object, Xata adds a set of read only fields:
 - `uploadUrl` - an upload URL generated with a signature. This URL allows write only access without a key but has an expiration time determined by the duration configured in `uploadUrlTimeout`. The field is generated on demand and needs to be explicitly requested in the query.
 - `attributes` - a JSON object that stores key-value properties specific to the file's media type. For instance, recognized image types will have properties like height and width stored within the attributes.
 
-When the file field is requested in a query, the returned file object will look like the following:
+When the file field is requested in a query, the returned xata_file object will look like the following:
 
 ```json
 {
@@ -452,11 +467,11 @@ When the file field is requested in a query, the returned file object will look
 
 The object fields, with the exception of `base64Content`, `url`, `signedUrl` and `uploadUrl`, can be used in query filters and summaries.
 
-The `file` column type does not support constraints like `not null` or `unique` or parameters like default value. The default value for a `file` column is `null`.
+The `xata_file` (`file`) column type does not support constraints like `not null` or `unique` or parameters like default value. The default value for a `xata_file` (`file`) column is `null`.
 
-### file[]
+### xata_file_array
 
-The `file[]` (file array) type represents a collection of files stored in the same table cell. Every array item is a JSON object similar to the file object, with the addition of an `id` field, which is used to refer to the item.
+The `xata_file_array` (`file[]`) type represents a collection of files stored in the same table cell. Every array item is a JSON object similar to the file object, with the addition of an `id` field, which is used to refer to the item.
 
 The `id` is automatically generated if it is not passed during the time of creation.
 
@@ -480,7 +495,7 @@ The following is an example of adding multiple files in a single column value:
 }
 ```
 
-All file fields described above are available for file array items. The fields are returned if selected in the query. For example selecting `images.id`, `images.name`, `images.mediaType`, `images.size`, `images.attributes` will return the following:
+All file fields described above are available for xata_file_array items. The fields are returned if selected in the query. For example selecting `images.id`, `images.name`, `images.mediaType`, `images.size`, `images.attributes` will return the following:
 
 ```json
 {
@@ -511,7 +526,7 @@ All file fields described above are available for file array items. The fields a
 
 Note that although the file fields can be queried, because the column value is an array it cannot be used in filters or summaries.
 
-The `file[]` column type does not support constraints like `not null` or `unique` or parameters like default values. The default value for a `file[]` column is an empty array `[]`.
+The `xata_file_array` column type does not support constraints like `not null` or `unique` or parameters like default values. The default value for a `xata_file_array` (`file[]`) column is an empty array `[]`.
 
 ### json
 
@@ -643,7 +658,7 @@ users = self.client.data().query("Users", {
 
 </TabbedCode>
 
-Note that `createdAt` in the above sample is an additional, explicitly created, datetime column.
+Note that `createdAt` in the above sample is an additional, explicitly created, timestamptz column.
 The default columns `xata.createdAt`,`xata.updatedAt` and `xata.version` are not supported for reverse link sorting.
 In [Postgres enabled](/docs/postgres) databases, the corresponding internal columns can be used for reverse link sorting.
 

diff --git a/040-Data-operations/101-get.mdx b/040-Data-operations/101-get.mdx
@@ -832,7 +832,7 @@ Translating the above filter in English: filter all users with a zipcode greater
 The example above demonstrates several operators:
 
 - `$gt`: which can be applied to number columns, and means "greater than".
-- `$contains`: which can be applied to string columns, and does a substring match.
+- `$contains`: which can be applied to text columns, and does a substring match.
 - `$any`: which can be used to create OR conditions. The record matches if any of the conditions enclosed are true.
 
 To see the rest of the operators available, check out the [Filtering](/docs/sdk/filtering) guide.

diff --git a/040-Data-operations/120-aggregate.mdx b/040-Data-operations/120-aggregate.mdx
@@ -317,9 +317,9 @@ results = xata.data().aggregate("titles", {
 
 ### Date histogram
 
-`dateHistogram` is a bucket-aggregation that splits the data into buckets by a datetime column. It is configured with the following parameters:
+`dateHistogram` is a bucket-aggregation that splits the data into buckets by a timestamptz (datetime) column. It is configured with the following parameters:
 
-- `column`: The column to use for bucketing. Must be of type datetime.
+- `column`: The column to use for bucketing. Must be of type timestamptz (datetime).
 - `interval`: The fixed interval to use when bucketing. It is formatted as number + unit of time, for example: `5d`, `20m`, `10s`.
 - `calendarInterval`: The calendar-aware interval to use when bucketing. Possible values are: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`.
 - `timezone`: The timezone to use for bucketing. By default, UTC is assumed. The accepted format is as an ISO 8601 UTC offset. For example: `+01:00` or

diff --git a/040-Data-operations/150-file-attachments.mdx b/040-Data-operations/150-file-attachments.mdx
@@ -9,7 +9,7 @@ published: true
 
 Xata offers general purpose file attachment capabilities. In order to simplify the management of large binary objects and to improve the developer experience, Xata integrates files support directly into the database itself. The aim is to offer a unified, seamless experience by exposing file support under one API, security model, and SDK. Using this approach, the [queries](/docs/sdk/get), [filters](/docs/sdk/filtering), [summaries](/docs/sdk/summarize), [aggregations](/docs/sdk/aggregate) from the SDK can also be used on the files' metadata. The metadata (file name, media type, tags) is also indexed for [search](/docs/sdk/search) in the optional Search store so it can be included in search results.
 
-![Add the file column type to start working with files](images/file-attachments-add.jpg)
+![Add the xata_file column type to start working with files](images/file-attachments-add.jpg)
 
 Xata provides three different ways to interact with file attachments within a file column in a database.
 
@@ -223,7 +223,7 @@ record, _ := recordsClient.Update(context.TODO(), xata.UpdateRecordRequest{
 
 ### Append a file to an array through updating a record
 
-In the following example the `photos` column is of type `file[]` (file array).
+In the following example the `photos` column is of type `xata_file_array` (`file[]`).
 The existing file ids from the array must be present in the update.
 
 <TabbedCode tabs={['TypeScript', 'Python', 'Go', 'JSON']}>
@@ -659,7 +659,7 @@ curl --request PUT 'https://{workspace}.{region}.upload.xata.sh/db/{db}:{branch}
 
 ### Append a file to an array using file APIs
 
-Column type is `file[]` (file array).
+Column type is `xata_file_array` (`file[]`).
 The `fileId` is optional and a unique id will be automatically generated if not provided.
 
 <TabbedCode tabs={['TypeScript', 'Python', 'Go', 'cURL']}>
@@ -724,7 +724,7 @@ curl 'https://{workspace}.{region}.xata.sh/db/{db}:{branch}/tables/{table}/data/
 
 </TabbedCode>
 
-`file[]` (file array) column type:
+`xata_file_array` (`file[]`)column type:
 
 <TabbedCode tabs={['TypeScript', 'Python', 'Go', 'cURL']}>
 ```ts
@@ -760,7 +760,7 @@ curl 'https://{workspace}.{region}.xata.sh/db/{db}:{branch}/tables/{table}/data/
 
 ### Delete a file from an array using file APIs
 
-Column type is `file[]` (file array).
+Column type is `xata_file_array` (`file[]`).
 `fileId` is required to identify the array item to be deleted.
 
 <TabbedCode tabs={['TypeScript', 'Python', 'Go', 'cURL']}>

diff --git a/040-Data-operations/160-image-transformations.mdx b/040-Data-operations/160-image-transformations.mdx
@@ -7,7 +7,7 @@ slug: sdk/image-transformations
 published: true
 ---
 
-Xata supports transformations for images stored in Xata's `File` and `File[]` [column types](/docs/sdk/file-attachments).
+Xata supports transformations for images stored in Xata's `xata_file` and `xata_file_array` [column types](/docs/sdk/file-attachments).
 
 Transformations are specified by modifying the `File`'s URL by adding `/transform/height=100,width=200/{fileId}`