docs: Add usage examples for Resource class methods

docs/reference/globals.md

@@ -26,27 +26,66 @@ const { tables, Resource } = require('harperdb');
 
 The global variables include:
 
-## `tables`
+### `tables`
 
-This is an object that holds all the tables for the default database (called `data`) as properties. Each of these property values is a table class that subclasses the Resource interface and provides access to the table through the Resource interface. For example, you can get a record from a table (in the default database) called 'my-table' with:
+This is an object with all the tables in the default database (the default database is "data"). Each table that has been declared or created in your `schema.graphql` file will be available as a property on this object, and the value will be the table class that can be used to interact with that table. The table classes implement the Resource API.
 
-```javascript
-import { tables } from 'harperdb';
-const { MyTable } = tables;
-async function getRecord() {
-	let record = await MyTable.get(recordId);
+**Schema Definition:**
+Tables are defined in your `schema.graphql` file using the `@table` directive. For example:
+
+```graphql
+type Product @table {
+	id: ID @primaryKey
+	name: String
+	price: Float
 }
 ```
 
-It is recommended that you [define a database](../developers/applications/defining-schemas) for all the tables that are required to exist in your application. This will ensure that the tables exist on the `tables` object. Also note that the property names follow a CamelCase convention for use in JavaScript and in the GraphQL Schemas, but these are translated to snake_case for the actual table names, and converted back to CamelCase when added to the `tables` object.
+Once declared, `Product` will be available as `tables.Product` (or `databases.data.Product`). This mapping is automatic: every table defined in the default database in your schema will appear as a property on the `tables` object. For more info, read our complete [guide on defining schemas](../developers/applications/defining-schemas).
 
-## `databases`
+#### Example
 
-This is an object that holds all the databases in Harper, and can be used to explicitly access a table by database name. Each database will be a property on this object, each of these property values will be an object with the set of all tables in that database. The default database, `databases.data` should equal the `tables` export. For example, if you want to access the "dog" table in the "dev" database, you could do so:
+```js
+const ProductTable = tables.Product; // Same as databases.data.Product
 
-```javascript
-import { databases } from 'harperdb';
-const { Dog } = databases.dev;
+// Within your Resource class:
+// Create a new record (ID generated)
+const created = await ProductTable.create({ name: 'Example', status: 'active' });
+
+// Retrieve by primary key
+const record = await ProductTable.get(created.id);
+
+// Insert or replace by ID
+await ProductTable.put(created.id, { ...record, status: 'inactive' });
+
+// Run a query
+const query = {
+	conditions: [{ attribute: 'status', value: 'active' }],
+	limit: 50,
+};
+
+for await (const record of ProductTable.search(query)) {
+	// Handle each row
+}
+```
+
+### `databases`
+
+This is an object with all the databases that have been defined in Harper (in the running instance). Each database that has been declared or created in your `schema.graphql` file will be available as a property on this object. The property values are objects containing the tables in that database, where each property is a table, just like the `tables` object. In fact, `databases.data === tables` should always be true.
+
+#### Example
+
+```js
+const ProductTable = databases.data.Product; // Default database
+const Events = databases.analytics.Events; // Another database
+
+// Create a new event record
+const event = await Events.create({ eventType: 'login', timestamp: Date.now() });
+
+// Query events
+for await (const e of Events.search({ conditions: [{ attribute: 'eventType', value: 'login' }] })) {
+	// Handle each event
+}
 ```
 
 ## `Resource`

docs/reference/resources/index.md

@@ -86,11 +86,65 @@ All Resource methods that are called from HTTP methods may directly return data
 
 ### `tables`
 
-This is an object with all the tables in the default database (the default database is "data"). Each table that has been declared or created will be available as a (standard) property on this object, and the value will be the table class that can be used to interact with that table. The table classes implement the Resource API.
+This is an object with all the tables in the default database (the default database is "data"). Each table that has been declared or created in your `schema.graphql` file will be available as a property on this object, and the value will be the table class that can be used to interact with that table. The table classes implement the Resource API.
+
+**Schema Definition:**
+Tables are defined in your `schema.graphql` file using the `@table` directive. For example:
+
+```graphql
+type Product @table {
+	id: ID @primaryKey
+	name: String
+	price: Float
+}
+```
+
+Once declared, `Product` will be available as `tables.Product` (or `databases.data.Product`). This mapping is automatic: every table defined in the default database in your schema will appear as a property on the `tables` object. For more info, read our complete [guide on defining schemas](../developers/applications/defining-schemas).
+
+#### Example
+
+```js
+const ProductTable = tables.Product; // Same as databases.data.Product
+
+// Within your Resource class:
+// Create a new record (ID generated)
+const created = await ProductTable.create({ name: 'Example', status: 'active' });
+
+// Retrieve by primary key
+const record = await ProductTable.get(created.id);
+
+// Insert or replace by ID
+await ProductTable.put(created.id, { ...record, status: 'inactive' });
+
+// Run a query
+const query = {
+	conditions: [{ attribute: 'status', value: 'active' }],
+	limit: 50,
+};
+
+for await (const record of ProductTable.search(query)) {
+	// Handle each row
+}
+```
 
 ### `databases`
 
-This is an object with all the databases that have been defined in Harper (in the running instance). Each database that has been declared or created will be available as a (standard) property on this object. The property values are an object with the tables in that database, where each property is a table, like the `tables` object. In fact, `databases.data === tables` should always be true.
+This is an object with all the databases that have been defined in Harper (in the running instance). Each database that has been declared or created in your `schema.graphql` file will be available as a property on this object. The property values are objects containing the tables in that database, where each property is a table, just like the `tables` object. In fact, `databases.data === tables` should always be true.
+
+#### Example
+
+```js
+const ProductTable = databases.data.Product; // Default database
+const Events = databases.analytics.Events; // Another database
+
+// Create a new event record
+const event = await Events.create({ eventType: 'login', timestamp: Date.now() });
+
+// Query events
+for await (const e of Events.search({ conditions: [{ attribute: 'eventType', value: 'login' }] })) {
+	// Handle each event
+}
+```
 
 ### `Resource`
 

versioned_docs/version-4.5/reference/globals.md

@@ -26,27 +26,66 @@ const { tables, Resource } = require('harperdb');
 
 The global variables include:
 
-## `tables`
+### `tables`
 
-This is an object that holds all the tables for the default database (called `data`) as properties. Each of these property values is a table class that subclasses the Resource interface and provides access to the table through the Resource interface. For example, you can get a record from a table (in the default database) called 'my-table' with:
+This is an object with all the tables in the default database (the default database is "data"). Each table that has been declared or created in your `schema.graphql` file will be available as a property on this object, and the value will be the table class that can be used to interact with that table. The table classes implement the Resource API.
 
-```javascript
-import { tables } from 'harperdb';
-const { MyTable } = tables;
-async function getRecord() {
-	let record = await MyTable.get(recordId);
+**Schema Definition:**
+Tables are defined in your `schema.graphql` file using the `@table` directive. For example:
+
+```graphql
+type Product @table {
+	id: ID @primaryKey
+	name: String
+	price: Float
 }
 ```
 
-It is recommended that you [define a database](../getting-started/quickstart) for all the tables that are required to exist in your application. This will ensure that the tables exist on the `tables` object. Also note that the property names follow a CamelCase convention for use in JavaScript and in the GraphQL Schemas, but these are translated to snake_case for the actual table names, and converted back to CamelCase when added to the `tables` object.
+Once declared, `Product` will be available as `tables.Product` (or `databases.data.Product`). This mapping is automatic: every table defined in the default database in your schema will appear as a property on the `tables` object. For more info, read our complete [guide on defining schemas](../developers/applications/defining-schemas).
 
-## `databases`
+#### Example
 
-This is an object that holds all the databases in Harper, and can be used to explicitly access a table by database name. Each database will be a property on this object, each of these property values will be an object with the set of all tables in that database. The default database, `databases.data` should equal the `tables` export. For example, if you want to access the "dog" table in the "dev" database, you could do so:
+```js
+const ProductTable = tables.Product; // Same as databases.data.Product
 
-```javascript
-import { databases } from 'harperdb';
-const { Dog } = databases.dev;
+// Within your Resource class:
+// Create a new record (ID generated)
+const created = await ProductTable.create({ name: 'Example', status: 'active' });
+
+// Retrieve by primary key
+const record = await ProductTable.get(created.id);
+
+// Insert or replace by ID
+await ProductTable.put(created.id, { ...record, status: 'inactive' });
+
+// Run a query
+const query = {
+	conditions: [{ attribute: 'status', value: 'active' }],
+	limit: 50,
+};
+
+for await (const record of ProductTable.search(query)) {
+	// Handle each row
+}
+```
+
+### `databases`
+
+This is an object with all the databases that have been defined in Harper (in the running instance). Each database that has been declared or created in your `schema.graphql` file will be available as a property on this object. The property values are objects containing the tables in that database, where each property is a table, just like the `tables` object. In fact, `databases.data === tables` should always be true.
+
+#### Example
+
+```js
+const ProductTable = databases.data.Product; // Default database
+const Events = databases.analytics.Events; // Another database
+
+// Create a new event record
+const event = await Events.create({ eventType: 'login', timestamp: Date.now() });
+
+// Query events
+for await (const e of Events.search({ conditions: [{ attribute: 'eventType', value: 'login' }] })) {
+	// Handle each event
+}
 ```
 
 ## `Resource`

versioned_docs/version-4.5/reference/resource.md

@@ -85,11 +85,65 @@ All Resource methods that are called from HTTP methods may directly return data
 
 ### `tables`
 
-This is an object with all the tables in the default database (the default database is "data"). Each table that has been declared or created will be available as a (standard) property on this object, and the value will be the table class that can be used to interact with that table. The table classes implement the Resource API.
+This is an object with all the tables in the default database (the default database is "data"). Each table that has been declared or created in your `schema.graphql` file will be available as a property on this object, and the value will be the table class that can be used to interact with that table. The table classes implement the Resource API.
+
+**Schema Definition:**
+Tables are defined in your `schema.graphql` file using the `@table` directive. For example:
+
+```graphql
+type Product @table {
+	id: ID @primaryKey
+	name: String
+	price: Float
+}
+```
+
+Once declared, `Product` will be available as `tables.Product` (or `databases.data.Product`). This mapping is automatic: every table defined in the default database in your schema will appear as a property on the `tables` object. For more info, read our complete [guide on defining schemas](../developers/applications/defining-schemas).
+
+#### Example
+
+```js
+const ProductTable = tables.Product; // Same as databases.data.Product
+
+// Within your Resource class:
+// Create a new record (ID generated)
+const created = await ProductTable.create({ name: 'Example', status: 'active' });
+
+// Retrieve by primary key
+const record = await ProductTable.get(created.id);
+
+// Insert or replace by ID
+await ProductTable.put(created.id, { ...record, status: 'inactive' });
+
+// Run a query
+const query = {
+	conditions: [{ attribute: 'status', value: 'active' }],
+	limit: 50,
+};
+
+for await (const record of ProductTable.search(query)) {
+	// Handle each row
+}
+```
 
 ### `databases`
 
-This is an object with all the databases that have been defined in Harper (in the running instance). Each database that has been declared or created will be available as a (standard) property on this object. The property values are an object with the tables in that database, where each property is a table, like the `tables` object. In fact, `databases.data === tables` should always be true.
+This is an object with all the databases that have been defined in Harper (in the running instance). Each database that has been declared or created in your `schema.graphql` file will be available as a property on this object. The property values are objects containing the tables in that database, where each property is a table, just like the `tables` object. In fact, `databases.data === tables` should always be true.
+
+#### Example
+
+```js
+const ProductTable = databases.data.Product; // Default database
+const Events = databases.analytics.Events; // Another database
+
+// Create a new event record
+const event = await Events.create({ eventType: 'login', timestamp: Date.now() });
+
+// Query events
+for await (const e of Events.search({ conditions: [{ attribute: 'eventType', value: 'login' }] })) {
+	// Handle each event
+}
+```
 
 ### `Resource`
 

versioned_docs/version-4.6/reference/globals.md

@@ -26,27 +26,66 @@ const { tables, Resource } = require('harperdb');
 
 The global variables include:
 
-## `tables`
+### `tables`
 
-This is an object that holds all the tables for the default database (called `data`) as properties. Each of these property values is a table class that subclasses the Resource interface and provides access to the table through the Resource interface. For example, you can get a record from a table (in the default database) called 'my-table' with:
+This is an object with all the tables in the default database (the default database is "data"). Each table that has been declared or created in your `schema.graphql` file will be available as a property on this object, and the value will be the table class that can be used to interact with that table. The table classes implement the Resource API.
 
-```javascript
-import { tables } from 'harperdb';
-const { MyTable } = tables;
-async function getRecord() {
-	let record = await MyTable.get(recordId);
+**Schema Definition:**
+Tables are defined in your `schema.graphql` file using the `@table` directive. For example:
+
+```graphql
+type Product @table {
+	id: ID @primaryKey
+	name: String
+	price: Float
 }
 ```
 
-It is recommended that you [define a database](../developers/applications/defining-schemas) for all the tables that are required to exist in your application. This will ensure that the tables exist on the `tables` object. Also note that the property names follow a CamelCase convention for use in JavaScript and in the GraphQL Schemas, but these are translated to snake_case for the actual table names, and converted back to CamelCase when added to the `tables` object.
+Once declared, `Product` will be available as `tables.Product` (or `databases.data.Product`). This mapping is automatic: every table defined in the default database in your schema will appear as a property on the `tables` object. For more info, read our complete [guide on defining schemas](../developers/applications/defining-schemas).
 
-## `databases`
+#### Example
 
-This is an object that holds all the databases in Harper, and can be used to explicitly access a table by database name. Each database will be a property on this object, each of these property values will be an object with the set of all tables in that database. The default database, `databases.data` should equal the `tables` export. For example, if you want to access the "dog" table in the "dev" database, you could do so:
+```js
+const ProductTable = tables.Product; // Same as databases.data.Product
 
-```javascript
-import { databases } from 'harperdb';
-const { Dog } = databases.dev;
+// Within your Resource class:
+// Create a new record (ID generated)
+const created = await ProductTable.create({ name: 'Example', status: 'active' });
+
+// Retrieve by primary key
+const record = await ProductTable.get(created.id);
+
+// Insert or replace by ID
+await ProductTable.put(created.id, { ...record, status: 'inactive' });
+
+// Run a query
+const query = {
+	conditions: [{ attribute: 'status', value: 'active' }],
+	limit: 50,
+};
+
+for await (const record of ProductTable.search(query)) {
+	// Handle each row
+}
+```
+
+### `databases`
+
+This is an object with all the databases that have been defined in Harper (in the running instance). Each database that has been declared or created in your `schema.graphql` file will be available as a property on this object. The property values are objects containing the tables in that database, where each property is a table, just like the `tables` object. In fact, `databases.data === tables` should always be true.
+
+#### Example
+
+```js
+const ProductTable = databases.data.Product; // Default database
+const Events = databases.analytics.Events; // Another database
+
+// Create a new event record
+const event = await Events.create({ eventType: 'login', timestamp: Date.now() });
+
+// Query events
+for await (const e of Events.search({ conditions: [{ attribute: 'eventType', value: 'login' }] })) {
+	// Handle each event
+}
 ```
 
 ## `Resource`