Restructure reading data docs to be index forward (#32402)

GitOrigin-RevId: e77df44b6ea8d5c5df49d3a0d0d139fbf964276e

_redirects

@@ -2,6 +2,9 @@
 # THIS LIST IS NOT ALPHABETICAL! It mostly is, but order matters for wildcards.
 /ai                                 /search 
 /database/import-export/airbyte     /database/import-export/streaming
+/database/indexes                   /database/reading-data/indexes
+/database/indexes/indexes-and-query-perf            /database/reading-data/indexes/indexes-and-query-perf
+/database/document-storage          /database/
 /client/react/project-setup         /client/react/deployment-urls
 /contact                            /production/contact
 /functions/http-endpoints		    /functions/http-actions

docs/auth/database-auth.mdx

@@ -46,8 +46,8 @@ the JWT):
 ### (optional) Users table schema
 
 You can define a `"users"` table, optionally with an
-[index](/docs/database/indexes/indexes.md) for efficient looking up the users in
-the database.
+[index](/docs/database/reading-data/indexes/indexes.md) for efficient looking up
+the users in the database.
 
 In the examples below we will use the `tokenIdentifier` from the
 `ctx.auth.getUserIdentity()` to identify the user, but you could use the
@@ -156,8 +156,8 @@ UI), it should start with `whsec_`. Set it as the value of the
 ### (optional) Users table schema
 
 You can define a `"users"` table, optionally with an
-[index](/docs/database/indexes/indexes.md) for efficient looking up the users in
-the database.
+[index](/docs/database/reading-data/indexes/indexes.md) for efficient looking up
+the users in the database.
 
 In the examples below we will use the `subject` from the
 `ctx.auth.getUserIdentity()` to identify the user, which should be set to the

docs/cli.md

@@ -157,7 +157,7 @@ Display a simple view of the
 
 The command supports `--limit` and `--order` flags to change data displayed. For
 more complex filters, use the dashboard data page or write a
-[query](/database/reading-data.mdx).
+[query](/docs/database/reading-data/reading-data.mdx).
 
 The `npx convex data <table>` command works with
 [system tables](/database/advanced/system-tables.mdx), such as `_storage`, in
@@ -210,7 +210,8 @@ This command will:
 1. Regenerate the [generated code](/generated-api/) in the `convex/_generated`
    directory.
 1. Bundle your Convex functions and their dependencies.
-1. Push your functions, [indexes](/docs/database/indexes/indexes.md), and
+1. Push your functions,
+   [indexes](/docs/database/reading-data/indexes/indexes.md), and
    [schema](/docs/database/schemas.mdx) to production.
 
 Once this command succeeds the new functions will be available immediately.
@@ -249,7 +250,8 @@ Deploy Key, this command will:
 1. Regenerate the [generated code](/generated-api/) in the `convex/_generated`
    directory.
 1. Bundle your Convex functions and their dependencies.
-1. Push your functions, [indexes](/docs/database/indexes/indexes.md), and
+1. Push your functions,
+   [indexes](/docs/database/reading-data/indexes/indexes.md), and
    [schema](/docs/database/schemas.mdx) to the deployment.
 1. Run a function specified by `--preview-run` (similar to the `--run` option
    for `npx convex dev`).

docs/dashboard/deployments/data.md

@@ -30,10 +30,11 @@ the top of the page.
 ![Data filters](/screenshots/data_filters.png)
 
 All fields in a document are filterable by the operations supported in Convex
-query syntax. [Equality](/docs/database/reading-data.mdx#equality-conditions)
-and [Comparison](/docs/database/reading-data.mdx#comparisons) when filtering in
-the dashboard share the same rules as a query using the Convex client. You may
-also filter based on the type of the field.
+query syntax.
+[Equality](/docs/database/reading-data/reading-data.mdx#equality-conditions) and
+[Comparison](/docs/database/reading-data/reading-data.mdx#comparisons) when
+filtering in the dashboard share the same rules as a query using the Convex
+client. You may also filter based on the type of the field.
 
 To add a filter, click the `+` next to an existing filter. If you add more than
 one condition, they will be evaluated using the `and` operation.
@@ -55,9 +56,9 @@ adding two filter conditions for `creationTime >= $time` and
 
 ## Writing custom queries
 
-You can write a [query](/docs/database/reading-data.mdx) directly in the
-dashboard. This allows you to perform arbitrary filtering and transformation of
-the data, including sorting, joins, grouping and aggregations.
+You can write a [query](/docs/database/reading-data/reading-data.mdx) directly
+in the dashboard. This allows you to perform arbitrary filtering and
+transformation of the data, including sorting, joins, grouping and aggregations.
 
 In the `⋮` overflow menu at the top of the data page click on the “Custom query”
 option.
@@ -196,7 +197,8 @@ menu at the top of the data page.
 
 This button will open a panel showing the saved
 [schema](/docs/database/schemas.mdx) and
-[indexes](/docs/database/indexes/indexes.md) associated with the selected table.
+[indexes](/docs/database/reading-data/indexes/indexes.md) associated with the
+selected table.
 
 Indexes that have not completed backfilling will be accompanied by a loading
 spinner next to their name.

docs/database.mdx

@@ -5,29 +5,93 @@ hide_table_of_contents: true
 pagination_prev: functions
 ---
 
-import RocketIcon from "@site/static/img/tutorial/icon_rocket.svg";
-
 The Convex database provides a relational data model, stores JSON-like
 documents, and can be used with or without a schema. It "just works," giving you
 predictable query performance in an easy-to-use interface.
 
 Query and mutation [functions](/docs/functions.mdx) read and write data through
-a lightweight JavaScript API. There is nothing to set up, and no need to write
+a lightweight JavaScript API. There is nothing to set up and no need to write
 any SQL. Just use JavaScript to express your app's needs.
 
-Start by learning about the basics of
-[Tables & Documents](/docs/database/document-storage.md),
-[Reading Data](/docs/database/reading-data.mdx) and
+Start by learning about the basics of [tables](#tables), [documents](#documents)
+and [schemas](#schemas) below, then move on to
+[Reading Data](/docs/database/reading-data/reading-data.mdx) and
 [Writing Data](/docs/database/writing-data.mdx).
 
 As your app grows more complex you'll need more from your database:
 
 - Relational data modeling with [Document IDs](/docs/database/document-ids.mdx)
-- Fast querying with [Indexes](/docs/database/indexes/indexes.md)
+- Fast querying with [Indexes](/docs/database/reading-data/indexes/indexes.md)
 - Exposing large datasets with
   [Paginated Queries](/docs/database/pagination.mdx)
 - Type safety by [Defining a Schema](/docs/database/schemas.mdx)
 - Interoperability with data
   [Import & Export](docs/database/import-export/import-export.mdx)
 
+## Tables
+
+Your Convex deployment contains tables that hold your app's data. Initially,
+your deployment contains no tables or documents.
+
+Each table springs into existence as soon as you add the first document to it.
+
+```javascript
+// `friends` table doesn't exist.
+await ctx.db.insert("friends", { name: "Jamie" });
+// Now it does, and it has one document.
+```
+
+You do not have to specify a schema upfront or create tables explicitly.
+
+## Documents
+
+Tables contain documents. Documents are very similar to JavaScript objects. They
+have fields and values, and you can nest arrays or objects within them.
+
+These are all valid Convex documents:
+
+```json
+{}
+{"name": "Jamie"}
+{"name": {"first": "Ari", "second": "Cole"}, "age": 60}
+```
+
+They can also contain references to other documents in other tables. See
+[Data Types](/docs/database/types.md) to learn more about the types supported in
+Convex and [Document IDs](/docs/database/document-ids.mdx) to learn about how to
+use those types to model your data.
+
+## Schemas
+
+Though optional, schemas ensure that your data looks exactly how you want. For a
+simple chat app, the schema will look like this:
+
+```typescript
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+// @snippet start schema
+export default defineSchema({
+  messages: defineTable({
+    author: v.id("users"),
+    body: v.string(),
+  }),
+});
+```
+
+You can choose to be as flexible as you want by using types such as `v.any()` or
+as specific as you want by precisely describing a `v.object()`.
+
+See [the schema documentation](/docs/database/schemas.mdx) to learn more about
+schemas.
+
+<CardLink
+  className="convex-hero-card"
+  item={{
+    href: "/database/reading-data",
+    docId: "database/reading-data/reading-data",
+    label: "Next: Reading Data",
+  }}
+/>
+
 <StackPosts query="database" />

docs/database/document-ids.mdx

@@ -68,7 +68,8 @@ You can follow references with `ctx.db.get`:
 const user = await ctx.db.get(book.ownerId);
 ```
 
-And [query for documents](/docs/database/reading-data.mdx) with a reference:
+And [query for documents](/docs/database/reading-data/reading-data.mdx) with a
+reference:
 
 ```ts
 const myBooks = await ctx.db

docs/database/pagination.mdx

@@ -47,8 +47,8 @@ To build this in Convex, define a query function that:
    - The arguments object may include properties as well.
 2. Calls
    [`.paginate(paginationOpts)`](/api/interfaces/server.OrderedQuery#paginate)
-   on a [database query](/docs/database/reading-data.mdx), passing in the
-   `PaginationOptions` and returning its result.
+   on a [database query](/docs/database/reading-data/reading-data.mdx), passing
+   in the `PaginationOptions` and returning its result.
    - The returned `page` in the
      [`PaginationResult`](/api/interfaces/server.PaginationResult) is an array
      of documents. You may
@@ -80,9 +80,9 @@ You can define paginated query functions that take arguments in addition to
 ### Transforming results
 
 You can apply arbitrary
-[transformations](/docs/database/reading-data.mdx#more-complex-queries) to the
-`page` property of the object returned by `paginate`, which contains the array
-of documents:
+[transformations](/docs/database/reading-data/reading-data.mdx#more-complex-queries)
+to the `page` property of the object returned by `paginate`, which contains the
+array of documents:
 
 <TSAndJSSnippet
   sourceTS={Messages}