add more docs to csv import #2514
Conversation
WalkthroughDocumentation for CSV imports was expanded and restructured. It now requires that all columns marked required are present, validates each row during import, and clarifies that each CSV row creates a new table row (an optional Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
src/routes/docs/products/databases/csv-imports/+page.markdoc (2)
36-38: Consider adding an example demonstrating null values.While the explanation is clear, an example CSV row showing null values would help users understand the practical application, especially since CSV handling of nulls can vary across tools.
For example, you could add:
Example: ```text $id,title,author,year,available f3k91x8b2q,Harry Potter,J.K. Rowling,1997,true mz7lq3dp5c,Unknown Title,null,null,false--- `87-91`: **Consider explaining the double-quote escaping for permissions.** The permissions example uses double-double-quotes (e.g., `""role:all""`), which is the correct CSV escaping convention. However, users unfamiliar with CSV escaping might find this confusing. Consider adding a brief explanation before or after the example: ```markdown An example of a valid permissions string (note that quotes are doubled for CSV escaping):
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: tests
- GitHub Check: build
🔇 Additional comments (4)
src/routes/docs/products/databases/csv-imports/+page.markdoc (4)
13-13: LGTM! Clear validation requirements and ID conflict behavior.The documentation clearly states that all required columns must be present and each row is validated. The clarification that imports fail on ID conflicts is important for users to understand.
Also applies to: 20-21
23-34: LGTM! Clear and comprehensive CSV example.The example effectively demonstrates the CSV structure with multiple column types (string, integer, boolean) and custom IDs.
40-55: LGTM! Comprehensive timestamp documentation.The section clearly explains the optional nature of timestamp columns and provides a well-formatted example with the correct ISO 8601 format specification.
57-68: Verify whitespace handling in array values.The example shows
"fiction, fantasy"with a space after the comma. Please verify whether Appwrite's CSV parser trims whitespace from array elements or preserves it. If spaces are preserved, the second element would befantasy(with leading space), which may not be the intended behavior.Consider updating the example to remove spaces for clarity:
-f3k91x8b2q,Harry Potter and the Sorcerer's Stone,J.K. Rowling,1997,true,"fiction, fantasy" -mz7lq3dp5c,The Fellowship of the Ring,J.R.R. Tolkien,1954,true,"fiction, fantasy" -x0v4p8ncq2,To Kill a Mockingbird,Harper Lee,1960,false,"fiction, nonfiction" +f3k91x8b2q,Harry Potter and the Sorcerer's Stone,J.K. Rowling,1997,true,"fiction,fantasy" +mz7lq3dp5c,The Fellowship of the Ring,J.R.R. Tolkien,1954,true,"fiction,fantasy" +x0v4p8ncq2,To Kill a Mockingbird,Harper Lee,1960,false,"fiction,nonfiction"Alternatively, explicitly document the whitespace behavior in the text.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
src/routes/docs/products/databases/csv-imports/+page.markdoc (2)
70-81: Clear explanation of table relationships.The section effectively demonstrates how to link rows across tables using foreign key IDs. The example is straightforward and easy to follow.
Note: The grammar issue mentioned in a previous review comment appears to have been resolved. Line 72 now correctly includes "you can provide."
83-102: Comprehensive permissions documentation with correct CSV escaping.The permissions section thoroughly covers the syntax, valid roles (including
all,guests,member, andadmin), and provides a complete example. The double-escaped quotes in the CSV example correctly demonstrate how to include permission strings within CSV fields.Note: The issue about missing the
allrole mentioned in a previous review comment appears to have been resolved. Line 93 now correctly lists all valid roles.
🧹 Nitpick comments (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc (1)
36-38: Consider adding a CSV example demonstrating null values.While the instruction to use
nullwithout quotes is clear, adding a brief CSV snippet showing null values in practice would help users understand the exact syntax. For example:$id,title,author,year,available f3k91x8b2q,Harry Potter,J.K. Rowling,1997,null
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: tests
🔇 Additional comments (4)
src/routes/docs/products/databases/csv-imports/+page.markdoc (4)
13-21: Excellent clarification of validation behavior.The explicit statements about required columns validation and ID conflict handling improve the documentation significantly and set clear expectations for users.
23-34: Clear and helpful example.The CSV example with multiple data types (string, integer, boolean) provides excellent guidance for users preparing their import files.
40-44: Well-documented timestamp handling.The explanation clearly conveys that timestamps are optional and will be auto-set when omitted, which helps users understand the behavior.
57-68: Comprehensive arrays documentation.The section clearly explains CSV array syntax with a practical example. The use of double quotes for comma-separated values is correctly documented.
There was a problem hiding this comment.
Besides the comments I left, we should probably also mention something about escaping. For example, what if I have text that contains a comma or a double quote?
Additionally, we interpret empty cell for a string attribute as empty string. If you want to set null for strings, you'll need to set the literal value null, with no quotes. For arrays, empty cell means empty array. For integers and booleans, empty cell means null. Double quote is the escape character.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc (1)
77-77: Fix grammar: missing "you" in the sentence.This issue was flagged in a previous review but remains unaddressed.
Apply this diff:
-If you want to create relationships between rows in different tables, can provide the `$id` of the related row in the foreign table. +If you want to create relationships between rows in different tables, you can provide the `$id` of the related row in the foreign table.
🧹 Nitpick comments (2)
src/routes/docs/products/databases/csv-imports/+page.markdoc (2)
62-62: Simplify heading per style guide.The heading "Add arrays" starts with a verb. As mentioned in previous review comments, the style guide prefers simple nouns for headings.
Based on learnings
Apply this diff:
-# Add arrays {% #add-arrays %} +# Arrays {% #arrays %}
88-88: Simplify heading per style guide.The heading "Set row permissions" starts with a verb. As mentioned in previous review comments, the style guide prefers simple nouns for headings.
Based on learnings
Apply this diff:
-# Set row permissions {% #set-row-permissions %} +# Row permissions {% #row-permissions %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: tests
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
src/routes/docs/products/databases/csv-imports/+page.markdoc (2)
77-77: Fix grammar: missing "you" in the sentence.The sentence is missing the subject "you" before "can provide".
Apply this diff:
-If you want to create relationships between rows in different tables, can provide the `$id` of the related row in the foreign table. +If you want to create relationships between rows in different tables, you can provide the `$id` of the related row in the foreign table.
115-115: Fix typo: "commans" should be "commas".Apply this diff:
-There are different ways to escape commas based on different scenarios. +There are different ways to escape commas based on different scenarios.
🧹 Nitpick comments (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc (1)
62-62: Consider simplifying the heading per style guide.The heading "Add arrays" could be simplified to "Arrays" to better align with the style guide preference for simple nouns. Other headings to consider: "Set row permissions" → "Row permissions".
Based on past review comments.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: tests
🔇 Additional comments (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc (1)
40-40: Clarify the null value handling for string columns.The instruction "use the value
nullwithout quotes" may be ambiguous to users. In standard CSV format, writing the literal textnullwould typically be interpreted as the string "null", not as a database null value.Please clarify:
- Does Appwrite treat the literal text
null(four characters) as a special keyword for null values?- If so, explicitly state this is Appwrite-specific behavior (e.g., "To add null values to a string column, write the literal text
nullin the cell—Appwrite will interpret this as a null value")- Consider adding an example showing the difference between an empty string and a null value in CSV format
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: tests
🔇 Additional comments (6)
src/routes/docs/products/databases/csv-imports/+page.markdoc (6)
23-60: LGTM!The examples and explanations for CSV structure, empty values, and timestamps are clear and technically accurate. The ISO 8601 format guidance is correct, and the type-specific handling of empty values is well-documented.
62-73: LGTM!The arrays section clearly explains the format and provides a good example of comma-separated values within quoted fields.
75-86: LGTM!The relationships section is clear and the grammar has been corrected from previous reviews. The example effectively demonstrates how to reference related rows using
$id.
88-107: LGTM!The permissions section has been updated to use the correct API role strings (
any,users,guests) based on previous feedback. The escaping of quotes in the CSV format is correct, and the reference to the permissions documentation is helpful.
120-146: LGTM!The double quote escaping explanation is correct (standard CSV convention), and the Console import instructions are clear and well-structured. The inclusion of dark/light mode images and background task information is helpful.
115-118: Verify array element comma escaping behavior for Appwrite CSV imports.In standard CSV format, if double-quotes are used to enclose fields, a double-quote appearing inside a field must be escaped by preceding it with another double quote. However, the documentation's example for array columns (
"one,two,""comma,allowed,here""") may be unclear or incorrect depending on how Appwrite's CSV parser handles array delimiters.The concern: In standard CSV, this example would parse to
one,two,"comma,allowed,here", but if commas delimit individual array elements in Appwrite's format, the embedded comma could still split the element incorrectly.Please verify and document whether Appwrite's CSV parser:
- Successfully supports commas within individual array elements using the doubled-quote escape sequence
- If so, provide a clear parsed result example
- If not, document the limitation or provide the correct escape method
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
src/routes/docs/products/databases/csv-imports/+page.markdoc (2)
77-77: Consider simplifying the wording.The phrase "the related row in the related table" is a bit redundant. Consider this more concise alternative:
-If you want to create relationships between rows in different tables, you can provide the `$id` of the related row in the related table. +If you want to create relationships between rows in different tables, you can provide the `$id` of the row from the related table.
45-45: Consider simplifying the heading for consistency.Based on the style guide, headings should prefer simple nouns over verbs. Consider simplifying this heading:
Based on coding guidelines.
-# Create and update timestamps {% #created-at-and-updated-at %} +# Timestamps {% #created-at-and-updated-at %}Or keep it more descriptive but use nouns:
-# Create and update timestamps {% #created-at-and-updated-at %} +# Creation and update timestamps {% #created-at-and-updated-at %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: tests
🔇 Additional comments (7)
src/routes/docs/products/databases/csv-imports/+page.markdoc (7)
23-34: LGTM!The example CSV is clear, well-formatted, and effectively demonstrates the basic structure with optional
$idcolumn.
36-44: LGTM!The empty values section is comprehensive and clearly explains the behavior for each column type.
45-60: LGTM!The timestamp section is clear, includes a properly formatted example, and correctly specifies the ISO 8601 requirement.
62-73: LGTM!The arrays section clearly demonstrates the quoted comma-separated format with a helpful example.
109-122: LGTM!The special characters section clearly explains how to escape commas and double quotes for different column types.
124-138: LGTM!The console import instructions are clear and well-structured with appropriate references to UI elements and images.
88-107: All permission syntax and role references are correct.The verification confirms:
- The double-quote escaping syntax
"read(""any"")"is correct for CSV format- All role strings (
any,guests,users,user:user_id) match the documented API roles in the REST API Roles section- The reference link
/docs/apis/rest#rolescorrectly points to valid permission role documentation- The examples demonstrate common, legitimate use cases
| An example of a valid permissions string: | ||
|
|
||
| ```text | ||
| "read(""any""),update(""users""),delete(""user:user_id"")" |
|
|
||
| ## Double quotes | ||
|
|
||
| If you want to add double quotes to a string column, you need to escape them by doubling them (`""`). |
There was a problem hiding this comment.
Let's explicitly mention that it will be treated as an array otherwise
Co-authored-by: Aditya Oberai <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc (1)
118-118: Consider adding a clearer explanation or breaking down the escaping example.The example
"one,two,""comma,allowed,here"""demonstrates proper escaping for array elements containing commas, but the nested quote escaping may be difficult for users to parse. Consider adding a step-by-step breakdown or a simpler explanation of the escaping rules.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/routes/docs/products/databases/csv-imports/+page.markdoc(2 hunks)
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-09-05T19:35:53.943Z
Learnt from: ebenezerdon
Repo: appwrite/website PR: 2372
File: src/routes/docs/tutorials/react/step-6/+page.markdoc:70-75
Timestamp: 2025-09-05T19:35:53.943Z
Learning: In React tutorial files, the correct Appwrite database instance to import is `tablesDB` from "../appwrite", not `databases`. The import statement should be `import { tablesDB } from "../appwrite"` to match the usage throughout the React tutorial code.
Applied to files:
src/routes/docs/products/databases/csv-imports/+page.markdoc
📚 Learning: 2025-09-05T19:35:04.162Z
Learnt from: ebenezerdon
Repo: appwrite/website PR: 2372
File: src/routes/docs/tutorials/nuxt/step-6/+page.markdoc:79-83
Timestamp: 2025-09-05T19:35:04.162Z
Learning: In Nuxt tutorial files, the correct Appwrite database instance to use is `tablesDB` (imported from "~/appwrite"), not `database`. All tablesDB method calls should use the object parameter format: listRows({ databaseId, tableId, queries }), createRow({ databaseId, tableId, rowId, data }), and deleteRow({ databaseId, tableId, rowId }).
Applied to files:
src/routes/docs/products/databases/csv-imports/+page.markdoc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: tests
- GitHub Check: build
🔇 Additional comments (2)
src/routes/docs/products/databases/csv-imports/+page.markdoc (2)
40-40: Clarify how to representnullvalues in CSV format.The phrase "use the value
nullwithout quotes" is ambiguous in CSV context. Does this mean:
- An empty CSV cell?
- The literal text
nullin the cell?- An unquoted null in the CSV file?
Please specify the exact CSV representation users should use.
120-122: Address past feedback: Clarify consequences of improper escaping.A previous reviewer requested explicitly mentioning what happens if double quotes are not properly escaped (line 122 context). Consider adding a note about potential parsing issues or unexpected behavior when escaping is omitted.
Based on past review comments.
| An example of a valid permissions string: | ||
|
|
||
| ```text | ||
| "read(""any""),update(""users""),delete(""user:user_id"")" |
There was a problem hiding this comment.
Address past feedback: Include team role in the example.
As requested in previous review comments, please add the team role to the permissions example to demonstrate its usage alongside other roles.
Based on past review comments.
🤖 Prompt for AI Agents
In src/routes/docs/products/databases/csv-imports/+page.markdoc around line 95,
the permissions example string lacks the `team` role; update that example to
include a `team` role entry alongside the existing roles so it demonstrates
usage (e.g., add a `team(...)` permission segment within the same
comma-separated string), ensuring punctuation and quoting match the surrounding
format.
Summary by CodeRabbit