diff --git a/docs/reference/globals.md b/docs/reference/globals.md index 0e09b54a..4316d897 100644 --- a/docs/reference/globals.md +++ b/docs/reference/globals.md @@ -28,25 +28,64 @@ The global variables include: ## `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). + +### Example + +```js +const Product = tables.Product; // Same as databases.data.Product + +// Create a new record (`id` is automatically generated when using `.create()`) +const created = await Product.create({ name: 'Shirt', price: 9.5 }); + +// Modify the record +await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 }); // 20% off! + +// Retrieve by primary key +const record = await Product.get(created.id); + +logger.info('New price:', record.price); + +// Query for all products with a `price` less than `8.00` +const query = { + conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }], +}; + +for await (const record of Product.search(query)) { + // ... +} +``` ## `databases` -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: +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. -```javascript -import { databases } from 'harperdb'; -const { Dog } = databases.dev; +### Example + +```js +const Product = 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` diff --git a/docs/reference/resources/index.md b/docs/reference/resources/index.md index 7c1014ac..82269149 100644 --- a/docs/reference/resources/index.md +++ b/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 Product = tables.Product; // Same as databases.data.Product + +// Create a new record (`id` is automatically generated when using `.create()`) +const created = await Product.create({ name: 'Shirt', price: 9.5 }); + +// Modify the record +await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 }); // 20% off! + +// Retrieve by primary key +const record = await Product.get(created.id); + +logger.info('New price:', record.price); + +// Query for all products with a `price` less than `8.00` +const query = { + conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }], +}; + +for await (const record of Product.search(query)) { + // ... +} +``` ### `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 Product = 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` diff --git a/versioned_docs/version-4.5/reference/globals.md b/versioned_docs/version-4.5/reference/globals.md index aa3a9190..05d899c9 100644 --- a/versioned_docs/version-4.5/reference/globals.md +++ b/versioned_docs/version-4.5/reference/globals.md @@ -28,25 +28,64 @@ The global variables include: ## `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). + +### Example + +```js +const Product = tables.Product; // Same as databases.data.Product + +// Create a new record (`id` is automatically generated when using `.create()`) +const created = await Product.create({ name: 'Shirt', price: 9.5 }); + +// Modify the record +await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 }); // 20% off! + +// Retrieve by primary key +const record = await Product.get(created.id); + +logger.info('New price:', record.price); + +// Query for all products with a `price` less than `8.00` +const query = { + conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }], +}; + +for await (const record of Product.search(query)) { + // ... +} +``` ## `databases` -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: +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. -```javascript -import { databases } from 'harperdb'; -const { Dog } = databases.dev; +### Example + +```js +const Product = 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` diff --git a/versioned_docs/version-4.5/reference/resource.md b/versioned_docs/version-4.5/reference/resource.md index f21b1d77..cc83541b 100644 --- a/versioned_docs/version-4.5/reference/resource.md +++ b/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 Product = tables.Product; // Same as databases.data.Product + +// Create a new record (`id` is automatically generated when using `.create()`) +const created = await Product.create({ name: 'Shirt', price: 9.5 }); + +// Modify the record +await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 }); // 20% off! + +// Retrieve by primary key +const record = await Product.get(created.id); + +logger.info('New price:', record.price); + +// Query for all products with a `price` less than `8.00` +const query = { + conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }], +}; + +for await (const record of Product.search(query)) { + // ... +} +``` ### `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 Product = 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` diff --git a/versioned_docs/version-4.6/reference/globals.md b/versioned_docs/version-4.6/reference/globals.md index c7616f01..bb2bb831 100644 --- a/versioned_docs/version-4.6/reference/globals.md +++ b/versioned_docs/version-4.6/reference/globals.md @@ -28,25 +28,64 @@ The global variables include: ## `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). + +### Example + +```js +const Product = tables.Product; // Same as databases.data.Product + +// Create a new record (`id` is automatically generated when using `.create()`) +const created = await Product.create({ name: 'Shirt', price: 9.5 }); + +// Modify the record +await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 }); // 20% off! + +// Retrieve by primary key +const record = await Product.get(created.id); + +logger.info('New price:', record.price); + +// Query for all products with a `price` less than `8.00` +const query = { + conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }], +}; + +for await (const record of Product.search(query)) { + // ... +} +``` ## `databases` -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: +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. -```javascript -import { databases } from 'harperdb'; -const { Dog } = databases.dev; +### Example + +```js +const Product = 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` diff --git a/versioned_docs/version-4.6/reference/resources/index.md b/versioned_docs/version-4.6/reference/resources/index.md index 603cca11..82269149 100644 --- a/versioned_docs/version-4.6/reference/resources/index.md +++ b/versioned_docs/version-4.6/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 Product = tables.Product; // Same as databases.data.Product + +// Create a new record (`id` is automatically generated when using `.create()`) +const created = await Product.create({ name: 'Shirt', price: 9.5 }); + +// Modify the record +await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 }); // 20% off! + +// Retrieve by primary key +const record = await Product.get(created.id); + +logger.info('New price:', record.price); + +// Query for all products with a `price` less than `8.00` +const query = { + conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }], +}; + +for await (const record of Product.search(query)) { + // ... +} +``` ### `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 Product = 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` @@ -102,7 +156,7 @@ This object provides extension points for extension components that wish to impl ### `transaction` -This provides a function for starting transactions. See the transactions section below for more information. +This provides a function for starting transactions. See the [transactions documentation](./transactions) for more information. ### `contentTypes` diff --git a/versioned_docs/version-4.7/reference/globals.md b/versioned_docs/version-4.7/reference/globals.md index 0e09b54a..4316d897 100644 --- a/versioned_docs/version-4.7/reference/globals.md +++ b/versioned_docs/version-4.7/reference/globals.md @@ -28,25 +28,64 @@ The global variables include: ## `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). + +### Example + +```js +const Product = tables.Product; // Same as databases.data.Product + +// Create a new record (`id` is automatically generated when using `.create()`) +const created = await Product.create({ name: 'Shirt', price: 9.5 }); + +// Modify the record +await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 }); // 20% off! + +// Retrieve by primary key +const record = await Product.get(created.id); + +logger.info('New price:', record.price); + +// Query for all products with a `price` less than `8.00` +const query = { + conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }], +}; + +for await (const record of Product.search(query)) { + // ... +} +``` ## `databases` -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: +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. -```javascript -import { databases } from 'harperdb'; -const { Dog } = databases.dev; +### Example + +```js +const Product = 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` diff --git a/versioned_docs/version-4.7/reference/resources/index.md b/versioned_docs/version-4.7/reference/resources/index.md index 7c1014ac..82269149 100644 --- a/versioned_docs/version-4.7/reference/resources/index.md +++ b/versioned_docs/version-4.7/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 Product = tables.Product; // Same as databases.data.Product + +// Create a new record (`id` is automatically generated when using `.create()`) +const created = await Product.create({ name: 'Shirt', price: 9.5 }); + +// Modify the record +await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 }); // 20% off! + +// Retrieve by primary key +const record = await Product.get(created.id); + +logger.info('New price:', record.price); + +// Query for all products with a `price` less than `8.00` +const query = { + conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }], +}; + +for await (const record of Product.search(query)) { + // ... +} +``` ### `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 Product = 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`