Skip to content

Update docs and blogs to TablesDB terminology#3037

Open
atharvadeosthale wants to merge 4 commits into
mainfrom
deprecate-old-terminology
Open

Update docs and blogs to TablesDB terminology#3037
atharvadeosthale wants to merge 4 commits into
mainfrom
deprecate-old-terminology

Conversation

@atharvadeosthale

Copy link
Copy Markdown
Member

Summary

  • Reworked docs and blog content to replace legacy databases terminology with current tables, rows, and columns language where appropriate
  • Updated SDK examples to use object-based params across the supported languages, and corrected a few snippets that needed signature-specific field ordering
  • Kept API references and legacy linkage plumbing intact where they are generated or intentionally preserved

Testing

  • Node SDK object-param payloads were smoke-tested against the generated SDK
  • Changed JS/TS/Deno code fences were parsed successfully
  • Repo checks passed, including bun run check and diff whitespace validation

@appwrite

appwrite Bot commented Jun 2, 2026

Copy link
Copy Markdown

Appwrite Website

Project ID: 69d7efb00023389e8d27

Sites (1)
Site Status Logs Preview QR
 website
69d7f2670014e24571ca
Building Building View Logs Preview URL QR Code

Website (appwrite/website)

Project ID: 684969cb000a2f6c0a02

Sites (1)
Site Status Logs Preview QR
 website
68496a17000f03d62013
Queued Queued View Logs Preview URL QR Code


Tip

Build commands execute in runtime containers during deployment

@adityaoberai adityaoberai left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please check for patterns of these issues across other blogs

Also, for every blog edited, we need to update the lastUpdated field in the frontmatter

- question: "How does the Meilisearch sync function stay in sync with new documents?"
answer: "By default the template syncs documents on demand when the function runs. To keep the index up to date automatically, configure the function to trigger on database events (document.create, document.update, document.delete) so every change is mirrored to Meilisearch in near real time."
- question: "How does the Meilisearch sync function stay in sync with new rows?"
answer: "By default the template syncs rows on demand when the function runs. To keep the index up to date automatically, configure the function to trigger on database row events so every change is mirrored to Meilisearch in near real time."

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will need to update the function template as well for this to work properly

Also, let's not remove the events from there, we should mention the correct ones instead

For more information about Appwrite and Appwrite Functions:

1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: These documents provide more information on how to use Appwrite Functions.
1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: Learn more about how to use Appwrite Functions.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: Learn more about how to use Appwrite Functions.
1. **[Appwrite Function Docs](/docs/products/functions)**: Learn more about how to use Appwrite Functions.

For more information about Appwrite and Appwrite Functions:

1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: These documents provide more information on how to use Appwrite Functions.
1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: Learn more about how to use Appwrite Functions.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: Learn more about how to use Appwrite Functions.
1. **[Appwrite Function Docs](/docs/products/functions)**: Learn more about how to use Appwrite Functions.

1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: These documents provide more information on how to use Appwrite Functions.
1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: Learn more about how to use Appwrite Functions.
2. **[Functions Announcement](https://dev.to/appwrite/serverless-your-way-unleashing-appwrite-functions-true-potential-2l4f)**: Read the full announcement on Functions 1.4.
3. **[Appwrite Discord](https://discord.com/invite/appwrite)**: Connect with other developers and the Appwrite team for discussion, questions, and collaboration.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
3. **[Appwrite Discord](https://discord.com/invite/appwrite)**: Connect with other developers and the Appwrite team for discussion, questions, and collaboration.
3. **[Appwrite Discord](/discord)**: Connect with other developers and the Appwrite team for discussion, questions, and collaboration.

1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: These documents provide more information on how to use Appwrite Functions.
1. **[Appwrite Function Docs](https://appwrite.io/docs/functions)**: Learn more about how to use Appwrite Functions.
2. **[Functions Announcement](https://dev.to/appwrite/serverless-your-way-unleashing-appwrite-functions-true-potential-2l4f)**: Read the full announcement on Functions 1.4.
3. **[Appwrite Discord](https://discord.com/invite/appwrite)**: Connect with other developers and the Appwrite team for discussion, questions, and collaboration.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
3. **[Appwrite Discord](https://discord.com/invite/appwrite)**: Connect with other developers and the Appwrite team for discussion, questions, and collaboration.
3. **[Appwrite Discord](/discord)**: Connect with other developers and the Appwrite team for discussion, questions, and collaboration.

Comment on lines -84 to -107
name: 'articles',
columns: [
{
key: 'title',
type: 'varchar',
size: 255,
required: true
},
{
key: 'summary',
type: 'text',
required: false
},
{
key: 'body',
type: 'mediumtext',
required: false
},
{
key: 'raw_data',
type: 'longtext',
required: false
}
]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not need a change, does it?

Comment on lines -80 to -90
Here’s what’s changed:

- Collections are now Tables
- Documents are now Rows
- Attributes are now Columns
The updated wording now centers Appwrite Databases around tables, rows, and columns.

To support the terminology change, we’ve added the TablesDB API.

A new API layer that helps you work with relational database concepts like tables, columns, and rows, without requiring any changes to your existing apps.

The old document-based methods are now deprecated and will no longer receive major upgrades. They will continue to receive security patches and essential maintenance, and we are ensuring backwards compatibility with those methods for the API, so there’s no need to migrate immediately if a specific issue arises.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes are unnecessary imho

Comment on lines +35 to +40
const promise = teams.create(
'teachers',
'Teachers',
['maths', 'sciences', 'arts', 'literature']
{
teamId: 'teachers',
name: 'Teachers',
roles: ['maths', 'sciences', 'arts', 'literature']
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

formatting issues?

Comment on lines +584 to +587
await teams.deleteMembership({
teamId: '<TEAM_ID>',
membershipId: '<MEMBERSHIP_ID>'
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These changes should not have been made in this PR, they add lots of extra bloat to review

Any changes to switch to object params should have been in a separate PR


- **Gradual migration.** You don't have to swap everything at once. Authentication can move first, then storage, then databases. Each service you migrate reduces your maintenance burden.
- **Data export and import.** Appwrite's databases are standard JSON/document stores. Exporting your existing data and importing it is straightforward for most data models.
- **Data export and import.** Appwrite's databases store standard JSON row data. Exporting your existing data and importing it is straightforward for most data models.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not the right phrasing, we should just say they accept JSON inputs that are mapped to the table schema

@atharvadeosthale

Copy link
Copy Markdown
Member Author

@greptile-apps review

@greptile-apps

greptile-apps Bot commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR migrates 204 docs and blog files from the legacy Appwrite Databases terminology (collections, documents, attributes) to the current TablesDB terminology (tables, rows, columns), and simultaneously updates SDK code examples to use object-based named parameters in place of positional arguments across JavaScript, TypeScript, Python, Ruby, and Deno tabs.

  • Terminology sweep: Every reference to "collection", "document", and "attribute" across docs, quick-starts, and blog posts is replaced with "table", "row", and "column"; API references and legacy linkage plumbing are intentionally preserved.
  • SDK snippet migration: listRows, createRow, updateRow, upsertRow, deleteRow, createRows, updateRows, upsertRows, deleteRows, incrementRowColumn, and decrementRowColumn examples are updated to the object-param style across all supported languages.
  • Notable concerns: One benchmark script directly accesses MariaDB with a bare table name (posts) instead of the Appwrite-internal prefixed format; a Flutter tutorial drops the size constraint when changing a column from String to Text, which is inconsistent with how the same "Text" type is documented in the quick-start page.

Confidence Score: 3/5

Two tutorial code spots introduce misleading or broken instructions that readers could follow and get stuck on; the remaining ~202 files are safe.

The MariaDB INSERT in the pagination benchmark explicitly bypasses the SDK and writes directly to the underlying database; using a bare table name (posts) rather than Appwrite's actual internal table identifier would silently fail for any reader trying to reproduce the benchmark. The Flutter tutorial also drops the required size field when switching a column from String to Text, while the quick-start page changed in this same PR still instructs readers to enter a size.

src/routes/blog/post/best-pagination-technique/+page.markdoc (direct MariaDB table name) and src/routes/blog/post/appwrite-realtime-for-flutter/+page.markdoc (missing column size) need a second look.

Important Files Changed

Filename Overview
src/routes/blog/post/best-pagination-technique/+page.markdoc Pagination code updated to TablesDB API and correct variable names; however the direct MariaDB INSERT table name was incorrectly changed from the Appwrite internal format to a bare posts table name
src/routes/blog/post/appwrite-realtime-for-flutter/+page.markdoc Flutter SDK calls migrated to TablesDB API (listRows, createRow, deleteRow); column type changed from String/size 25 to Text without size, which is inconsistent with quick-start docs
src/routes/blog/post/build-fullstack-svelte-appwrite/+page.markdoc Full migration to TablesDB API across imports and SDK calls; userId column changed to Text instead of the more appropriate Varchar for an indexable ID field
src/routes/blog/post/ai-crystal-ball/+page.markdoc SDK migrated to TablesDB, column types updated correctly, file path typo fixed, addDestiny/getDestiny functions correctly rewritten
src/routes/docs/products/databases/quick-start/+page.markdoc Updated UI instructions from 'String' to 'Text' column type and CLI command updated; size requirement text kept intact
src/routes/docs/products/databases/rows/+page.markdoc SDK calls updated to object-based params, variable renamed from doc to row, CLI command updated; changes look consistent and correct
src/routes/docs/products/databases/queries/+page.markdoc Python/Ruby keyword-arg format added, variable names changed from doc to row, 'string operations' renamed to 'text operations'; well-aligned changes
src/routes/docs/products/databases/bulk-operations/+page.markdoc JS/TS bulk row methods migrated to object-based params; consistent with SDK changes
src/routes/docs/products/databases/relationships/+page.markdoc createRelationshipColumn migrated from positional to named-object params; field names correctly renamed
src/routes/docs/products/databases/tables/+page.markdoc Column type descriptions updated (varchar now described as 'Short text column'); accurate terminology change

Comments Outside Diff (1)

  1. src/routes/blog/post/appwrite-realtime-for-flutter/+page.markdoc, line 56-62 (link)

    P1 Size field removed for a Text column type that still requires a size per the quick-start docs

    The name column changed from Type: String, Size: 25 to Type: Text with the Size line dropped entirely. However, in docs/products/databases/quick-start/+page.markdoc (also changed in this PR), the updated instruction for creating a "Text" column still reads: "Enter Column key and Size. For example, title and 100." — meaning "Text" type columns still require a size to be specified. Omitting the size here leaves a reader without a value to enter and silently changes the semantic: if "Text" maps to the large text column type rather than varchar, the field loses its 25-character size cap and can no longer be fully indexed, which would affect any query that filters or sorts by name.

    Prompt To Fix With AI
    This is a comment left during a code review.
    Path: src/routes/blog/post/appwrite-realtime-for-flutter/+page.markdoc
    Line: 56-62
    
    Comment:
    **Size field removed for a Text column type that still requires a size per the quick-start docs**
    
    The `name` column changed from `Type: String, Size: 25` to `Type: Text` with the `Size` line dropped entirely. However, in `docs/products/databases/quick-start/+page.markdoc` (also changed in this PR), the updated instruction for creating a "Text" column still reads: *"Enter **Column key** and **Size**. For example, `title` and `100`."* — meaning "Text" type columns still require a size to be specified. Omitting the size here leaves a reader without a value to enter and silently changes the semantic: if "Text" maps to the large `text` column type rather than `varchar`, the field loses its 25-character size cap and can no longer be fully indexed, which would affect any query that filters or sorts by name.
    
    How can I resolve this? If you propose a fix, please make it concise.

    Fix in Claude Code Fix in Codex

Fix All in Claude Code Fix All in Codex

Prompt To Fix All With AI
Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
src/routes/blog/post/best-pagination-technique/+page.markdoc:173
**Incorrect internal MariaDB table name in direct-SQL benchmark script**

The benchmark blog explicitly states it bypasses the Appwrite SDK and inserts directly into MariaDB: *"We could use Appwrite SDK, but talking directly to MariaDB offers more optional write queries for large datasets."* The old name `_project_${config.projectId}_collection_posts` was the actual internal naming convention Appwrite used when storing collection data. Changing it to just `posts` is almost certainly wrong — in any Appwrite version, including TablesDB, the underlying MariaDB table would have a namespace prefix, not the bare user-supplied table ID. A reader who follows this script verbatim to reproduce the benchmark would execute the INSERT against a non-existent table or the wrong table entirely.

### Issue 2 of 3
src/routes/blog/post/appwrite-realtime-for-flutter/+page.markdoc:56-62
**Size field removed for a Text column type that still requires a size per the quick-start docs**

The `name` column changed from `Type: String, Size: 25` to `Type: Text` with the `Size` line dropped entirely. However, in `docs/products/databases/quick-start/+page.markdoc` (also changed in this PR), the updated instruction for creating a "Text" column still reads: *"Enter **Column key** and **Size**. For example, `title` and `100`."* — meaning "Text" type columns still require a size to be specified. Omitting the size here leaves a reader without a value to enter and silently changes the semantic: if "Text" maps to the large `text` column type rather than `varchar`, the field loses its 25-character size cap and can no longer be fully indexed, which would affect any query that filters or sorts by name.

### Issue 3 of 3
src/routes/blog/post/build-fullstack-svelte-appwrite/+page.markdoc:100-107
**`userId` column changed from `String` to `Text` — a short ID field should be `Varchar`**

`userId` is a short identifier (typically ≤ 36 characters for a UUID) that callers will almost certainly filter on (e.g., `Query.equal('userId', currentUser.$id)`). The `varchar` / "Short text" type is fully indexable up to 768 characters and is the correct pick for this field. The `text` column type uses prefix indexing only, cannot be fully indexed, and has no effective size constraint. If this "Text" instruction maps to the `text` column type in the new Console UI, the tutorial inadvertently guides readers to create a column that cannot be efficiently queried by user ID.

Reviews (1): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile

@@ -174,7 +173,7 @@ for(let i = 0; i < 100; i++) {
index++;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Incorrect internal MariaDB table name in direct-SQL benchmark script

The benchmark blog explicitly states it bypasses the Appwrite SDK and inserts directly into MariaDB: "We could use Appwrite SDK, but talking directly to MariaDB offers more optional write queries for large datasets." The old name _project_${config.projectId}_collection_posts was the actual internal naming convention Appwrite used when storing collection data. Changing it to just posts is almost certainly wrong — in any Appwrite version, including TablesDB, the underlying MariaDB table would have a namespace prefix, not the bare user-supplied table ID. A reader who follows this script verbatim to reproduce the benchmark would execute the INSERT against a non-existent table or the wrong table entirely.

Prompt To Fix With AI
This is a comment left during a code review.
Path: src/routes/blog/post/best-pagination-technique/+page.markdoc
Line: 173

Comment:
**Incorrect internal MariaDB table name in direct-SQL benchmark script**

The benchmark blog explicitly states it bypasses the Appwrite SDK and inserts directly into MariaDB: *"We could use Appwrite SDK, but talking directly to MariaDB offers more optional write queries for large datasets."* The old name `_project_${config.projectId}_collection_posts` was the actual internal naming convention Appwrite used when storing collection data. Changing it to just `posts` is almost certainly wrong — in any Appwrite version, including TablesDB, the underlying MariaDB table would have a namespace prefix, not the bare user-supplied table ID. A reader who follows this script verbatim to reproduce the benchmark would execute the INSERT against a non-existent table or the wrong table entirely.

How can I resolve this? If you propose a fix, please make it concise.

Fix in Claude Code Fix in Codex

Comment on lines 100 to 107
- `createdAt` (DateTime, required)
- `updatedAt` (DateTime, required)
```

Notice that the `category` attribute is an enumerated type with a set of predefined values. This structured approach helps us organize and filter expenses effectively. We have both a `date` attribute and a `createdAt` attribute because when an expense is created is not necessarily the same as when it occurred.
Notice that the `category` column is an enumerated type with a set of predefined values. This structured approach helps us organize and filter expenses effectively. We have both a `date` column and a `createdAt` column because when an expense is created is not necessarily the same as when it occurred.

To ensure that users can only access their own expenses, Open the collection's **Settings** tab and scroll to **Permissions**. Click **Add role**, select **Users** and check **Create** permission.
To ensure that users can only access their own expenses, Open the table's **Settings** tab and scroll to **Permissions**. Click **Add role**, select **Users** and check **Create** permission.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 userId column changed from String to Text — a short ID field should be Varchar

userId is a short identifier (typically ≤ 36 characters for a UUID) that callers will almost certainly filter on (e.g., Query.equal('userId', currentUser.$id)). The varchar / "Short text" type is fully indexable up to 768 characters and is the correct pick for this field. The text column type uses prefix indexing only, cannot be fully indexed, and has no effective size constraint. If this "Text" instruction maps to the text column type in the new Console UI, the tutorial inadvertently guides readers to create a column that cannot be efficiently queried by user ID.

Prompt To Fix With AI
This is a comment left during a code review.
Path: src/routes/blog/post/build-fullstack-svelte-appwrite/+page.markdoc
Line: 100-107

Comment:
**`userId` column changed from `String` to `Text` — a short ID field should be `Varchar`**

`userId` is a short identifier (typically ≤ 36 characters for a UUID) that callers will almost certainly filter on (e.g., `Query.equal('userId', currentUser.$id)`). The `varchar` / "Short text" type is fully indexable up to 768 characters and is the correct pick for this field. The `text` column type uses prefix indexing only, cannot be fully indexed, and has no effective size constraint. If this "Text" instruction maps to the `text` column type in the new Console UI, the tutorial inadvertently guides readers to create a column that cannot be efficiently queried by user ID.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Claude Code Fix in Codex

@adityaoberai adityaoberai left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving to unblock

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants