diff --git a/docs/administration/administration.md b/docs/administration/administration.md index e4d2b0d1..651d8922 100644 --- a/docs/administration/administration.md +++ b/docs/administration/administration.md @@ -22,7 +22,7 @@ Harper provides rapid horizontal scaling capabilities through [node cloning func Harper provides robust capabilities for analytics and observability to facilitate effective and informative monitoring: -- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](../technical-details/reference/analytics). +- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](../reference/analytics). - A large variety of real-time statistics about load, system information, database metrics, thread usage can be retrieved through the [`system_information` API](../developers/operations-api/system-operations). - Information about the current cluster configuration and status can be found in the [cluster APIs](../developers/operations-api/clustering). - Analytics and system information can easily be exported to Prometheus with our [Prometheus exporter component](https://github.com/HarperDB-Add-Ons/prometheus_exporter), making it easy visualize and monitor Harper with Graphana. diff --git a/docs/deployments/configuration.md b/docs/deployments/configuration.md index 4cac621d..569237e9 100644 --- a/docs/deployments/configuration.md +++ b/docs/deployments/configuration.md @@ -715,7 +715,7 @@ Harper's logger supports defining multiple logging configurations for different `logging.external` -The `logging.external` section can be used to define logging for all external components that use the [`logger` API](../technical-details/reference/globals). For example: +The `logging.external` section can be used to define logging for all external components that use the [`logger` API](../reference/globals). For example: ```yaml logging: @@ -1233,7 +1233,7 @@ The name of the component. This will be used to name the folder where the compon `package` - _Type_: string -A reference to your [component](../technical-details/reference/components/applications#adding-components-to-root) package. This could be a remote git repo, a local folder/file or an NPM package. Harper will add this package to a package.json file and call `npm install` on it, so any reference that works with that paradigm will work here. +A reference to your [component](../reference/components/applications#adding-components-to-root) package. This could be a remote git repo, a local folder/file or an NPM package. Harper will add this package to a package.json file and call `npm install` on it, so any reference that works with that paradigm will work here. Read more about npm install [here](https://docs.npmjs.com/cli/v8/commands/npm-install) diff --git a/docs/developers/applications/data-loader.md b/docs/developers/applications/data-loader.md index 9aed9546..ba9f433c 100644 --- a/docs/developers/applications/data-loader.md +++ b/docs/developers/applications/data-loader.md @@ -15,7 +15,7 @@ dataLoader: files: 'data/*.json' ``` -The Data Loader is an [Extension](../../technical-details/reference/components#extensions) and supports the standard `files` configuration option. +The Data Loader is an [Extension](../../reference/components#extensions) and supports the standard `files` configuration option. ## Data File Format @@ -176,6 +176,6 @@ rest: true ## Related Documentation -- [Built-In Components](../../technical-details/reference/components/built-in-extensions) -- [Extensions](../../technical-details/reference/components/extensions) +- [Built-In Components](../../reference/components/built-in-extensions) +- [Extensions](../../reference/components/extensions) - [Bulk Operations](../operations-api/bulk-operations) - For loading data via the Operations API diff --git a/docs/developers/applications/defining-schemas.md b/docs/developers/applications/defining-schemas.md index df239ca5..9df28255 100644 --- a/docs/developers/applications/defining-schemas.md +++ b/docs/developers/applications/defining-schemas.md @@ -78,7 +78,7 @@ type Brand @table @export { } ``` -Once this is defined we can use the `brand` attribute as a [property in our product instances](../../technical-details/reference/resources/) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). +Once this is defined we can use the `brand` attribute as a [property in our product instances](../../reference/resources/) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). Again, the foreign key may be a multi-valued array (array of keys referencing the target table records). For example, if we had a list of features that references a Feature table: @@ -241,7 +241,7 @@ The `@sealed` directive specifies that no additional properties should be allowe ### Defined vs Dynamic Schemas -If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../technical-details/reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. +If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. ### Field Types @@ -257,7 +257,7 @@ Harper supports the following field types in addition to user defined (object) t - `Any`: Any primitive, object, or array is allowed - `Date`: A Date object - `Bytes`: Binary data as a Buffer or Uint8Array -- `Blob`: Binary data as a [Blob](../../technical-details/reference/blob), designed for large blocks of data that can be streamed. It is recommend that you use this for binary data that will typically be larger than 20KB. +- `Blob`: Binary data as a [Blob](../../reference/blob), designed for large blocks of data that can be streamed. It is recommend that you use this for binary data that will typically be larger than 20KB. #### Renaming Tables diff --git a/docs/developers/applications/index.md b/docs/developers/applications/index.md index cacbe09b..39022047 100644 --- a/docs/developers/applications/index.md +++ b/docs/developers/applications/index.md @@ -67,21 +67,21 @@ flowchart TD Rest --> Networking ``` -> As of Harper v4.6, a new, **experimental** component system has been introduced called **plugins**. Plugins are a **new iteration of the existing extension system**. They are simultaneously a simplification and an extensibility upgrade. Instead of defining multiple methods (`start` vs `startOnMainThread`, `handleFile` vs `setupFile`, `handleDirectory` vs `setupDirectory`), plugins only have to define a single `handleApplication` method. Plugins are **experimental**, and complete documentation is available on the [plugin API](../../technical-details/reference/components/plugins) page. In time we plan to deprecate the concept of extensions in favor of plugins, but for now, both are supported. +> As of Harper v4.6, a new, **experimental** component system has been introduced called **plugins**. Plugins are a **new iteration of the existing extension system**. They are simultaneously a simplification and an extensibility upgrade. Instead of defining multiple methods (`start` vs `startOnMainThread`, `handleFile` vs `setupFile`, `handleDirectory` vs `setupDirectory`), plugins only have to define a single `handleApplication` method. Plugins are **experimental**, and complete documentation is available on the [plugin API](../../reference/components/plugins) page. In time we plan to deprecate the concept of extensions in favor of plugins, but for now, both are supported. Beyond applications and extensions, components are further classified as built-in or custom. **Built-in** components are included with Harper by default and can be directly referenced by their name. The `graphqlSchema`, `rest`, and `jsResource` extensions used in the previous application example are all examples of built-in extensions. **Custom** components must use external references, generally npm or GitHub packages, and are often included as dependencies within the `package.json` of the component. > Harper maintains a number of custom components that are available on `npm` and `GitHub`, such as the [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs) extension or the [`@harperdb/status-check`](https://github.com/HarperDB/status-check) application. -Harper does not currently include any built-in applications, making "custom applications" a bit redundant. Generally, we just say "application". However, there is a multitude of both built-in and custom extensions, and so the documentation refers to them as such. A complete list of built-in extensions is available in the [Built-In Extensions](../../technical-details/reference/components/built-in-extensions) documentation page, and the list of custom extensions and applications is available below. +Harper does not currently include any built-in applications, making "custom applications" a bit redundant. Generally, we just say "application". However, there is a multitude of both built-in and custom extensions, and so the documentation refers to them as such. A complete list of built-in extensions is available in the [Built-In Extensions](../../reference/components/built-in-extensions) documentation page, and the list of custom extensions and applications is available below. This guide is going to walk you through building a basic Harper application using a set of built-in extensions. -> The Technical Details section of the documentation contains a [complete reference for all aspects of components](../../technical-details/reference/components), applications, extensions, and more. +> The Reference -> Components section of the documentation contains a [complete reference for all aspects of components](../../reference/components), applications, extensions, and more. ## Custom Functionality with JavaScript -[The getting started guide](../../getting-started/first-harper-app) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../technical-details/reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +[The getting started guide](../../getting-started/first-harper-app) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: @@ -211,11 +211,11 @@ Breed.sourcedFrom(BreedSource, { expiration: 3600 }); The [caching documentation](caching) provides much more information on how to use Harper's powerful caching capabilities and set up data sources. -Harper provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../../technical-details/reference/globals) and the [Resource interface](../../technical-details/reference/resource). +Harper provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../../reference/globals) and the [Resource interface](../../reference/resource). ## Configuring Applications/Components -For complete information of configuring applications, refer to the [Component Configuration](../../technical-details/reference/components) reference page. +For complete information of configuring applications, refer to the [Component Configuration](../../reference/components) reference page. ## Define Fastify Routes diff --git a/docs/getting-started/first-harper-app.md b/docs/getting-started/first-harper-app.md index 5390f98a..75cdfbab 100644 --- a/docs/getting-started/first-harper-app.md +++ b/docs/getting-started/first-harper-app.md @@ -163,7 +163,7 @@ http://localhost:9926/Dog/?breed=Husky&name=Balto&select(id,name,breed) Congratulations, you now have created a secure database application backend with a table, a well-defined structure, access controls, and a functional REST endpoint with query capabilities! See the [REST documentation for more information on HTTP access](../developers/rest) and see the [Schema reference](../developers/applications/defining-schemas) for more options for defining schemas. -> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../technical-details/reference/graphql). +> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../reference/graphql). ## Key Takeaway diff --git a/docs/getting-started/harper-concepts.md b/docs/getting-started/harper-concepts.md index c42f2fe9..0e88b0d1 100644 --- a/docs/getting-started/harper-concepts.md +++ b/docs/getting-started/harper-concepts.md @@ -8,13 +8,13 @@ As you begin your journey with Harper, there are a few concepts and definitions ## Components -Harper components are a core Harper concept defined as flexible JavaScript based extensions of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../technical-details/reference/globals) (such as Resource, databases, and tables). +Harper components are a core Harper concept defined as flexible JavaScript based extensions of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../reference/globals) (such as Resource, databases, and tables). -A key aspect to components are their extensibility; components can be built on other components. For example, a [Harper Application](../developers/applications/) is a component that uses many other components. The [application template](https://github.com/HarperDB/application-template) demonstrates many of Harper's built-in components such as [rest](../technical-details/reference/components/built-in-extensions#rest) (for automatic REST endpoint generation), [graphqlSchema](../technical-details/reference/components/built-in-extensions#graphqlschema) (for table schema definitions), and many more. +A key aspect to components are their extensibility; components can be built on other components. For example, a [Harper Application](../developers/applications/) is a component that uses many other components. The [application template](https://github.com/HarperDB/application-template) demonstrates many of Harper's built-in components such as [rest](../reference/components/built-in-extensions#rest) (for automatic REST endpoint generation), [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) (for table schema definitions), and many more. ## Applications -Applications are a subset of components that cannot be used directly and must depend on other extensions. Examples include defining schemas (using [graphqlSchema](../technical-details/reference/components/built-in-extensions#graphqlschema) built-in extension), defining custom resources (using [jsResource](../technical-details/reference/components/built-in-extensions#jsresource) built-in extension), hosting static files (using [static](../technical-details/reference/components/built-in-extensions#static) built-in extension), enabling REST querying of resources (using [rest](../technical-details/reference/components/built-in-extensions#rest) built-in extension), and running [Next.js](https://github.com/HarperDB/nextjs), [Astro](https://github.com/HarperDB/astro), or [Apollo](https://github.com/HarperDB/apollo) applications through their respective extensions. +Applications are a subset of components that cannot be used directly and must depend on other extensions. Examples include defining schemas (using [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) built-in extension), defining custom resources (using [jsResource](../reference/components/built-in-extensions#jsresource) built-in extension), hosting static files (using [static](../reference/components/built-in-extensions#static) built-in extension), enabling REST querying of resources (using [rest](../reference/components/built-in-extensions#rest) built-in extension), and running [Next.js](https://github.com/HarperDB/nextjs), [Astro](https://github.com/HarperDB/astro), or [Apollo](https://github.com/HarperDB/apollo) applications through their respective extensions. ## Resources diff --git a/docs/getting-started/what-is-harper.md b/docs/getting-started/what-is-harper.md index b69edaa2..25c0fb98 100644 --- a/docs/getting-started/what-is-harper.md +++ b/docs/getting-started/what-is-harper.md @@ -34,7 +34,7 @@ When you are ready for something a little more advanced, start [customizing your Finally, when it’s time to deploy, explore [replication](../developers/replication/) between nodes. -If you would like to jump into the most advanced capabilities, learn about [components](../technical-details/reference/components/). +If you would like to jump into the most advanced capabilities, learn about [components](../reference/components/). :::warning Need help? Please don’t hesitate to [reach out](https://www.harpersystems.dev/contact). diff --git a/docs/technical-details/_category_.json b/docs/reference/_category_.json similarity index 54% rename from docs/technical-details/_category_.json rename to docs/reference/_category_.json index b965ef06..d6302ac2 100644 --- a/docs/technical-details/_category_.json +++ b/docs/reference/_category_.json @@ -1,10 +1,10 @@ { - "label": "Technical Details", + "label": "Reference", "position": 4, "link": { "type": "generated-index", - "title": "Technical Details Documentation", + "title": "Reference Documentation", "description": "Reference documentation and technical specifications", - "keywords": ["technical-details"] + "keywords": ["reference", "specifications"] } } diff --git a/docs/technical-details/reference/analytics.md b/docs/reference/analytics.md similarity index 100% rename from docs/technical-details/reference/analytics.md rename to docs/reference/analytics.md diff --git a/docs/technical-details/reference/architecture.md b/docs/reference/architecture.md similarity index 100% rename from docs/technical-details/reference/architecture.md rename to docs/reference/architecture.md diff --git a/versioned_docs/version-4.6/technical-details/reference/blob.md b/docs/reference/blob.md similarity index 97% rename from versioned_docs/version-4.6/technical-details/reference/blob.md rename to docs/reference/blob.md index a62ba2eb..9b6b1fb2 100644 --- a/versioned_docs/version-4.6/technical-details/reference/blob.md +++ b/docs/reference/blob.md @@ -103,4 +103,4 @@ if (blob.size === undefined) { ``` -See the [configuration](../../deployments/configuration) documentation for more information on configuring where blob are stored. +See the [configuration](../deployments/configuration) documentation for more information on configuring where blob are stored. diff --git a/versioned_docs/version-4.6/technical-details/reference/components/applications.md b/docs/reference/components/applications.md similarity index 93% rename from versioned_docs/version-4.6/technical-details/reference/components/applications.md rename to docs/reference/components/applications.md index 28cdcdcf..0bde610c 100644 --- a/versioned_docs/version-4.6/technical-details/reference/components/applications.md +++ b/docs/reference/components/applications.md @@ -12,7 +12,7 @@ Harper offers several approaches to managing applications that differ between lo Harper is designed to be simple to run locally. Generally, Harper should be installed locally on a machine using a global package manager install (i.e. `npm i -g harperdb`). -> Before continuing, ensure Harper is installed and the `harperdb` CLI is available. For more information, review the [installation guide](../../../deployments/install-harper/). +> Before continuing, ensure Harper is installed and the `harperdb` CLI is available. For more information, review the [installation guide](../../deployments/install-harper/). When developing an application locally there are a number of ways to run it on Harper. @@ -52,7 +52,7 @@ Alternatively, to mimic interfacing with a hosted Harper instance, use operation Similar to the previous section, if the main thread needs to be restarted, start and stop the Harper instance manually (with the application deployed). Upon Harper startup, the application will automatically be loaded and executed across all threads. -> Not all [component operations](../../../developers/operations-api/components) are available via CLI. When in doubt, switch to using the Operations API via network requests to the local Harper instance. +> Not all [component operations](../../developers/operations-api/components) are available via CLI. When in doubt, switch to using the Operations API via network requests to the local Harper instance. For example, to properly _deploy_ a `test-application` locally, the command would look like: @@ -69,7 +69,7 @@ Keep in mind that using a local file path for `package` will only work locally; ## Remote Management -Managing applications on a remote Harper instance is best accomplished through [component operations](../../../developers/operations-api/components), similar to using the `deploy` command locally. Before continuing, always backup critical Harper instances. Managing, deploying, and executing applications can directly impact a live system. +Managing applications on a remote Harper instance is best accomplished through [component operations](../../developers/operations-api/components), similar to using the `deploy` command locally. Before continuing, always backup critical Harper instances. Managing, deploying, and executing applications can directly impact a live system. Remote Harper instances work very similarly to local Harper instances. The primary application management operations still include `deploy_component`, `drop_component`, and `restart`. @@ -110,7 +110,7 @@ Furthermore, the `package` field can be set to any valid [npm dependency value]( - For applications deployed to npm, specify the package name: `package="@harperdb/status-check"` - For applications on GitHub, specify the URL: `package="https://github.com/HarperDB/status-check"`, or the shorthand `package=HarperDB/status-check` - Private repositories also work if the correct SSH keys are on the server: `package="git+ssh://git@github.com:HarperDB/secret-applications.git"` - - Reference the [SSH Key](../../../developers/operations-api/components#add-ssh-key) operations for more information on managing SSH keys on a remote instance + - Reference the [SSH Key](../../developers/operations-api/components#add-ssh-key) operations for more information on managing SSH keys on a remote instance - Even tarball URLs are supported: `package="https://example.com/application.tar.gz"` > When using git tags, we highly recommend that you use the semver directive to ensure consistent and reliable installation by npm. In addition to tags, you can also reference branches or commit numbers. diff --git a/docs/technical-details/reference/components/built-in-extensions.md b/docs/reference/components/built-in-extensions.md similarity index 95% rename from docs/technical-details/reference/components/built-in-extensions.md rename to docs/reference/components/built-in-extensions.md index 72648416..81cb456e 100644 --- a/docs/technical-details/reference/components/built-in-extensions.md +++ b/docs/reference/components/built-in-extensions.md @@ -6,7 +6,7 @@ title: Built-In Extensions Harper provides extended features using built-in extensions. They do **not** need to be installed with a package manager, and simply must be specified in a config to run. These are used throughout many Harper docs, guides, and examples. Unlike custom extensions which have their own semantic versions, built-in extensions follow Harper's semantic version. -For more information read the [Components, Applications, and Extensions](../../../developers/applications/) documentation section. +For more information read the [Components, Applications, and Extensions](../../developers/applications/) documentation section. - [Built-In Extensions](#built-in-extensions) - [dataLoader](#dataloader) @@ -32,7 +32,7 @@ Load data from JSON or YAML files into Harper tables as part of component deploy This component is an [Extension](..#extensions) and can be configured with the `files` configuration option. -Complete documentation for this feature is available here: [Data Loader](../../../developers/applications/data-loader) +Complete documentation for this feature is available here: [Data Loader](../../developers/applications/data-loader) ```yaml dataLoader: @@ -45,7 +45,7 @@ Specify custom endpoints using [Fastify](https://fastify.dev/). This component is a [Resource Extension](./extensions#resource-extension) and can be configured with the [`files` and `urlPath`](./extensions#resource-extension-configuration) configuration options. -Complete documentation for this feature is available here: [Define Fastify Routes](../../../developers/applications/define-routes) +Complete documentation for this feature is available here: [Define Fastify Routes](../../developers/applications/define-routes) ```yaml fastifyRoutes: @@ -70,7 +70,7 @@ Specify schemas for Harper tables and resources via GraphQL schema syntax. This component is a [Resource Extension](./extensions#resource-extension) and can be configured with the [`files` and `urlPath`](./extensions#resource-extension-configuration) configuration options. -Complete documentation for this feature is available here: [Defining Schemas](../../../developers/applications/defining-schemas) +Complete documentation for this feature is available here: [Defining Schemas](../../developers/applications/defining-schemas) ```yaml graphqlSchema: @@ -81,7 +81,7 @@ graphqlSchema: Specify custom, JavaScript based Harper resources. -Refer to the Application [Custom Functionality with JavaScript](../../../developers/applications/#custom-functionality-with-javascript) guide, or [Resource Class](../resources/) reference documentation for more information on custom resources. +Refer to the Application [Custom Functionality with JavaScript](../../developers/applications/#custom-functionality-with-javascript) guide, or [Resource Class](../resources/) reference documentation for more information on custom resources. This component is a [Resource Extension](./extensions#resource-extension) and can be configured with the [`files` and `urlPath`](./extensions#resource-extension-configuration) configuration options. @@ -125,7 +125,7 @@ loadEnv: Enable automatic REST endpoint generation for exported resources with this component. -Complete documentation for this feature is available here: [REST](../../../developers/rest) +Complete documentation for this feature is available here: [REST](../../developers/rest) ```yaml rest: true @@ -153,7 +153,7 @@ Specify roles for Harper tables and resources. This component is a [Resource Extension](./extensions#resource-extension) and can be configured with the [`files` and `urlPath`](./extensions#resource-extension-configuration) configuration options. -Complete documentation for this feature is available here: [Defining Roles](../../../developers/applications/defining-roles) +Complete documentation for this feature is available here: [Defining Roles](../../developers/applications/defining-roles) ```yaml roles: diff --git a/docs/technical-details/reference/components/configuration.md b/docs/reference/components/configuration.md similarity index 97% rename from docs/technical-details/reference/components/configuration.md rename to docs/reference/components/configuration.md index 3e6108a0..2175a03d 100644 --- a/docs/technical-details/reference/components/configuration.md +++ b/docs/reference/components/configuration.md @@ -4,7 +4,7 @@ title: Component Configuration # Component Configuration -> For information on the distinction between the types of components (applications and extensions), refer to beginning of the [Applications](../../../developers/applications) documentation section. +> For information on the distinction between the types of components (applications and extensions), refer to beginning of the [Applications](../../developers/applications) documentation section. Harper components are configured with a `config.yaml` file located in the root of the component module directory. This file is how an components configures other components it depends on. Each entry in the file starts with a component name, and then configuration values are indented below it. diff --git a/docs/technical-details/reference/components/extensions.md b/docs/reference/components/extensions.md similarity index 100% rename from docs/technical-details/reference/components/extensions.md rename to docs/reference/components/extensions.md diff --git a/docs/technical-details/reference/components/index.md b/docs/reference/components/index.md similarity index 96% rename from docs/technical-details/reference/components/index.md rename to docs/reference/components/index.md index d2953776..30ce276d 100644 --- a/docs/technical-details/reference/components/index.md +++ b/docs/reference/components/index.md @@ -16,7 +16,7 @@ title: Components All together, the support for implementing a feature is the extension, and the actual implementation of the feature is the application. -For more information on the differences between applications and extensions, refer to the beginning of the [Applications](../../developers/applications/) guide documentation section. +For more information on the differences between applications and extensions, refer to the beginning of the [Applications](../developers/applications/) guide documentation section. This technical reference section has detailed information on various component systems: diff --git a/docs/technical-details/reference/components/plugins.md b/docs/reference/components/plugins.md similarity index 100% rename from docs/technical-details/reference/components/plugins.md rename to docs/reference/components/plugins.md diff --git a/versioned_docs/version-4.4/technical-details/reference/content-types.md b/docs/reference/content-types.md similarity index 98% rename from versioned_docs/version-4.4/technical-details/reference/content-types.md rename to docs/reference/content-types.md index 8d0feaf3..b7d223f4 100644 --- a/versioned_docs/version-4.4/technical-details/reference/content-types.md +++ b/docs/reference/content-types.md @@ -32,4 +32,4 @@ MessagePack is another efficient binary format like CBOR, with support for all H Comma-separated values is an easy to use and understand format that can be readily imported into spreadsheets or used for data processing. CSV lacks hierarchical structure for most data types, and shouldn't be used for frequent/production use, but when you need it, it is available. -In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../../developers/rest) for more information on how to do this. +In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../developers/rest) for more information on how to do this. diff --git a/docs/technical-details/reference/data-types.md b/docs/reference/data-types.md similarity index 93% rename from docs/technical-details/reference/data-types.md rename to docs/reference/data-types.md index 50493a82..df03e718 100644 --- a/docs/technical-details/reference/data-types.md +++ b/docs/reference/data-types.md @@ -4,7 +4,7 @@ title: Data Types # Data Types -Harper supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (Harper’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. Harper supports MessagePack and CBOR, which allows for all of Harper supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../../developers/rest)). Available data types include: +Harper supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (Harper’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. Harper supports MessagePack and CBOR, which allows for all of Harper supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../developers/rest)). Available data types include: (Note that these labels are descriptive, they do not necessarily correspond to the GraphQL schema type names, but the schema type names are noted where possible) diff --git a/docs/technical-details/reference/dynamic-schema.md b/docs/reference/dynamic-schema.md similarity index 98% rename from docs/technical-details/reference/dynamic-schema.md rename to docs/reference/dynamic-schema.md index 6eaa6bed..14fdd9af 100644 --- a/docs/technical-details/reference/dynamic-schema.md +++ b/docs/reference/dynamic-schema.md @@ -36,7 +36,7 @@ Harper automatically creates two audit attributes used on each record if the tab ### Dynamic Schema Example -To better understand the behavior let’s take a look at an example. This example utilizes [Harper API operations](../../developers/operations-api/databases-and-tables). +To better understand the behavior let’s take a look at an example. This example utilizes [Harper API operations](../developers/operations-api/databases-and-tables). **Create a Database** diff --git a/docs/technical-details/reference/globals.md b/docs/reference/globals.md similarity index 96% rename from docs/technical-details/reference/globals.md rename to docs/reference/globals.md index 16863e21..0e09b54a 100644 --- a/docs/technical-details/reference/globals.md +++ b/docs/reference/globals.md @@ -38,7 +38,7 @@ async function getRecord() { } ``` -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. +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. ## `databases` @@ -59,7 +59,7 @@ This returns the user object with permissions/authorization information based on ## `logger` -This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../../administration/logging/standard-logging) for more information. +This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../administration/logging/standard-logging) for more information. ## `server` @@ -256,7 +256,7 @@ Properties: ### `server.config` -This provides access to the Harper configuration object. This comes from the [harperdb-config.yaml](../../deployments/configuration) (parsed into object form). +This provides access to the Harper configuration object. This comes from the [harperdb-config.yaml](../deployments/configuration) (parsed into object form). ### `server.recordAnalytics(value, metric, path?, method?, type?)` @@ -304,7 +304,7 @@ server.resources.getMatch('/NewResource/some-id', 'my-protocol'); ### `server.operation(operation: Object, context?: Object, authorize?: boolean)` -Execute an operation from the [Operations API](../../developers/operations-api) +Execute an operation from the [Operations API](../developers/operations-api) Parameters: @@ -312,7 +312,7 @@ Parameters: - `context` - `Object` - `{ username: string}` - _optional_ - The specified user - `authorize` - `boolean` - _optional_ - Indicate the operation should authorize the user or not. Defaults to `false` -Returns a `Promise` with the operation's response as per the [Operations API documentation](../../developers/operations-api). +Returns a `Promise` with the operation's response as per the [Operations API documentation](../developers/operations-api). ### `server.nodes` diff --git a/docs/technical-details/reference/graphql.md b/docs/reference/graphql.md similarity index 98% rename from docs/technical-details/reference/graphql.md rename to docs/reference/graphql.md index 1626e97c..cc43eec9 100644 --- a/docs/technical-details/reference/graphql.md +++ b/docs/reference/graphql.md @@ -4,7 +4,7 @@ title: GraphQL Querying # GraphQL Querying -Harper supports GraphQL in a variety of ways. It can be used for [defining schemas](../../developers/applications/defining-schemas), and for querying [Resources](./resources/). +Harper supports GraphQL in a variety of ways. It can be used for [defining schemas](../developers/applications/defining-schemas), and for querying [Resources](./resources/). Get started by setting `graphql: true` in `config.yaml`. diff --git a/docs/technical-details/reference/headers.md b/docs/reference/headers.md similarity index 100% rename from docs/technical-details/reference/headers.md rename to docs/reference/headers.md diff --git a/docs/technical-details/reference/index.md b/docs/reference/index.md similarity index 100% rename from docs/technical-details/reference/index.md rename to docs/reference/index.md diff --git a/docs/technical-details/reference/limits.md b/docs/reference/limits.md similarity index 100% rename from docs/technical-details/reference/limits.md rename to docs/reference/limits.md diff --git a/docs/technical-details/reference/resources/index.md b/docs/reference/resources/index.md similarity index 98% rename from docs/technical-details/reference/resources/index.md rename to docs/reference/resources/index.md index 0b0f6f8d..7c1014ac 100644 --- a/docs/technical-details/reference/resources/index.md +++ b/docs/reference/resources/index.md @@ -272,7 +272,7 @@ When a resource is accessed as a data source: ### `operation(operationObject: Object, authorize?: boolean): Promise` -This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). +This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). ### `allowStaleWhileRevalidate(entry: { version: number, localTime: number, expiresAt: number, value: object }, id): boolean` @@ -373,7 +373,7 @@ type MyTable @table { } ``` -See the [schema documentation](../../developers/applications/defining-schemas) for more information on computed attributes. +See the [schema documentation](../developers/applications/defining-schemas) for more information on computed attributes. ### `primaryKey` @@ -490,7 +490,7 @@ Table.search({ **Chained Attributes/Properties** -Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../developers/applications/defining-schemas), see the [REST documentation](../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: +Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../developers/applications/defining-schemas) (in addition to the [schema documentation](../developers/applications/defining-schemas), see the [REST documentation](../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: ```javascript Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] }); diff --git a/docs/technical-details/reference/resources/instance-binding.md b/docs/reference/resources/instance-binding.md similarity index 97% rename from docs/technical-details/reference/resources/instance-binding.md rename to docs/reference/resources/instance-binding.md index 2b13ec71..11b9fc72 100644 --- a/docs/technical-details/reference/resources/instance-binding.md +++ b/docs/reference/resources/instance-binding.md @@ -79,7 +79,7 @@ This object provides extension points for extension components that wish to impl ### `transaction` -This provides a function for starting transactions. See the [transactions documentation](../../../technical-details/transactions) for more information. +This provides a function for starting transactions. See the [transactions documentation](../transactions) for more information. ### `contentTypes` @@ -253,7 +253,7 @@ When a resource is accessed as a data source: ### `operation(operationObject: Object, authorize?: boolean): Promise` -This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). +This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). ### `allowStaleWhileRevalidate(entry: { version: number, localTime: number, expiresAt: number, value: object }, id): boolean` @@ -360,7 +360,7 @@ type MyTable @table { } ``` -See the [schema documentation](../../../developers/applications/defining-schemas) for more information on computed attributes. +See the [schema documentation](../../developers/applications/defining-schemas) for more information on computed attributes. ### `primaryKey` @@ -442,7 +442,7 @@ export class BlogPost extends tables.BlogPost { } ``` -Please see the [transaction documentation](../../../technical-details/transactions) for more information on how transactions work in Harper. +Please see the [transaction documentation](../transactions) for more information on how transactions work in Harper. ### Query @@ -477,7 +477,7 @@ Table.search({ **Chained Attributes/Properties** -Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../../developers/applications/defining-schemas), see the [REST documentation](../../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: +Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../developers/applications/defining-schemas), see the [REST documentation](../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: ```javascript Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] }); diff --git a/docs/technical-details/reference/resources/migration.md b/docs/reference/resources/migration.md similarity index 100% rename from docs/technical-details/reference/resources/migration.md rename to docs/reference/resources/migration.md diff --git a/docs/technical-details/reference/storage-algorithm.md b/docs/reference/storage-algorithm.md similarity index 100% rename from docs/technical-details/reference/storage-algorithm.md rename to docs/reference/storage-algorithm.md diff --git a/docs/technical-details/reference/transactions.md b/docs/reference/transactions.md similarity index 100% rename from docs/technical-details/reference/transactions.md rename to docs/reference/transactions.md diff --git a/redirects.ts b/redirects.ts index 5a0bc5cd..c3a3fd13 100644 --- a/redirects.ts +++ b/redirects.ts @@ -170,7 +170,7 @@ function generateDocsRedirects(basePath: string): RedirectRule[] { { from: withBase('/audit-logging'), to: withBase('/administration/logging/audit-logging') }, { from: withBase('/jobs'), to: withBase('/administration/jobs') }, { from: withBase('/upgrade-hdb-instance'), to: withBase('/deployments/upgrade-hdb-instance') }, - { from: withBase('/reference'), to: withBase('/technical-details/reference/') }, + { from: withBase('/reference'), to: withBase('/reference/') }, { from: withBase('/operations-api'), to: withBase('/developers/operations-api/') }, { from: withBase('/rest'), to: withBase('/developers/rest') }, { from: withBase('/api'), to: withBase('/developers/operations-api/') }, @@ -269,7 +269,7 @@ export function createRedirects(existingPath: string, basePath: string = ''): st // - /deployments/harper-cli (explicit) // - /developers/sql-guide/* (has explicit redirect) // - /developers/operations-api/* (has explicit redirects) - // - /technical-details/reference/* (has explicit redirect) + // - /reference/* (has explicit redirect) return redirects.length > 0 ? redirects : undefined; } diff --git a/release-notes/v4-tucker/4.2.0.md b/release-notes/v4-tucker/4.2.0.md index 5c7a075c..26ef9404 100644 --- a/release-notes/v4-tucker/4.2.0.md +++ b/release-notes/v4-tucker/4.2.0.md @@ -12,11 +12,11 @@ HarperDB 4.2 introduces a new interface to accessing our core database engine wi ### Resource API -The [Resource API](/docs/technical-details/reference/resources) is the new interface for accessing data in HarperDB. It utilizes a uniform interface for accessing data in HarperDB database/tables and is designed to easily be implemented or extended for defining customized application logic for table access or defining custom external data sources. This API has support for connecting resources together for caching and delivering data change and message notifications in real-time. The [Resource API documentation details this interface](/docs/technical-details/reference/resources). +The [Resource API](/docs/reference/resources) is the new interface for accessing data in HarperDB. It utilizes a uniform interface for accessing data in HarperDB database/tables and is designed to easily be implemented or extended for defining customized application logic for table access or defining custom external data sources. This API has support for connecting resources together for caching and delivering data change and message notifications in real-time. The [Resource API documentation details this interface](/docs/reference/resources). ### Component Architecture -HarperDB's custom functions have evolved towards a full component architecture; our internal functionality is defined as components, and this can be used in a modular way in conjunction with user components. These can all easily be configured and loaded through configuration files, and there is now a [well-defined interface for creating your own components](/docs/technical-details/reference/components/extensions). Components can easily be deployed/installed into HarperDB using [NPM and Github references as well](/docs/technical-details/reference/components/applications?_highlight=github#adding-components-to-root). +HarperDB's custom functions have evolved towards a full component architecture; our internal functionality is defined as components, and this can be used in a modular way in conjunction with user components. These can all easily be configured and loaded through configuration files, and there is now a [well-defined interface for creating your own components](/docs/reference/components/extensions). Components can easily be deployed/installed into HarperDB using [NPM and Github references as well](/docs/reference/components/applications?_highlight=github#adding-components-to-root). ### Configurable Database Schemas diff --git a/release-notes/v4-tucker/4.3.0.md b/release-notes/v4-tucker/4.3.0.md index fdb0c7af..7f0332bb 100644 --- a/release-notes/v4-tucker/4.3.0.md +++ b/release-notes/v4-tucker/4.3.0.md @@ -95,7 +95,7 @@ HarperDB's MQTT now supports the retain handling flags for subscriptions that ar HarperDB now supports basic conflict-free data type (CRDT) updates that allow properties to be individually updated and merged when separate properties are updated on different threads or nodes. Individual property CRDT updates are automatically performed when you update individual properties through the resource API. Individual property CRDT updates are used when making `PATCH` requests through the REST API. -The CRDT functionality also supports explicit incrementation to merge multiple parallel incrementation requests with proper summing. See the [Resource API for more information](/docs/technical-details/reference/resources). +The CRDT functionality also supports explicit incrementation to merge multiple parallel incrementation requests with proper summing. See the [Resource API for more information](/docs/reference/resources). #### Configuration Improvements diff --git a/release-notes/v4-tucker/4.4.0.md b/release-notes/v4-tucker/4.4.0.md index c2afa787..8b6623be 100644 --- a/release-notes/v4-tucker/4.4.0.md +++ b/release-notes/v4-tucker/4.4.0.md @@ -24,7 +24,7 @@ Certain operations can now be replicated across the cluster, including the deplo ### Computed Properties -Computed properties allow applications to define properties that are computed from other properties, allowing for composite properties that are calculated from other data stored in records without requiring actual storage of the computed value. For example, you could have a computed property for a full name based on first and last, or age/duration based on a date. Computed properties are also foundational for custom indexes. See the [schema documentation](/docs/developers/applications/defining-schemas), [Resource API](/docs/technical-details/reference/resources), and our blog post on [computed properties](https://www.harpersystems.dev/development/tutorials/how-to-create-custom-indexes-with-computed-properties) for more information. +Computed properties allow applications to define properties that are computed from other properties, allowing for composite properties that are calculated from other data stored in records without requiring actual storage of the computed value. For example, you could have a computed property for a full name based on first and last, or age/duration based on a date. Computed properties are also foundational for custom indexes. See the [schema documentation](/docs/developers/applications/defining-schemas), [Resource API](/docs/reference/resources), and our blog post on [computed properties](https://www.harpersystems.dev/development/tutorials/how-to-create-custom-indexes-with-computed-properties) for more information. ### Custom Indexing @@ -32,7 +32,7 @@ Custom indexes can now be defined using computed properties to allow for unlimit ### Native Graph Support -HarperDB now includes provisional support for native [GraphQL querying functionality](/docs/technical-details/reference/graphql). This allows for querying of graph data using GraphQL syntax. This is provisional and some APIs may be updated in the future. +HarperDB now includes provisional support for native [GraphQL querying functionality](/docs/reference/graphql). This allows for querying of graph data using GraphQL syntax. This is provisional and some APIs may be updated in the future. ### Dynamic Certificate Management diff --git a/release-notes/v4-tucker/4.5.0.md b/release-notes/v4-tucker/4.5.0.md index 41437a69..d5395603 100644 --- a/release-notes/v4-tucker/4.5.0.md +++ b/release-notes/v4-tucker/4.5.0.md @@ -10,7 +10,7 @@ title: 4.5.0 ### Blob Storage -4.5 introduces a new [Blob storage system](/docs/technical-details/reference/blob), that is designed to efficiently handle large binary objects, with built-in support for streaming large content/media in and out of storage. This provides significantly better performance and functionality for large unstructured data, such as HTML, images, video, and other large files. Components can leverage this functionality through the JavaScript `Blob` interface, and the new `createBlob` function. Blobs are fully replicated and integrated. Harper can also coerce strings to `Blob`s (when dictated by the field type), making it feasible to use blobs for large string data, including with MQTT messaging. +4.5 introduces a new [Blob storage system](/docs/reference/blob), that is designed to efficiently handle large binary objects, with built-in support for streaming large content/media in and out of storage. This provides significantly better performance and functionality for large unstructured data, such as HTML, images, video, and other large files. Components can leverage this functionality through the JavaScript `Blob` interface, and the new `createBlob` function. Blobs are fully replicated and integrated. Harper can also coerce strings to `Blob`s (when dictated by the field type), making it feasible to use blobs for large string data, including with MQTT messaging. ### Password Hashing Upgrade diff --git a/release-notes/v4-tucker/index.md b/release-notes/v4-tucker/index.md index eb6b69d1..32bf51c7 100644 --- a/release-notes/v4-tucker/index.md +++ b/release-notes/v4-tucker/index.md @@ -23,7 +23,7 @@ HarperDB version 4 ([Tucker release](v4-tucker/tucker)) represents major step fo ## [4.5](v4-tucker/4.5.25) -- Blob Storage - 4.5 introduces a new [Blob storage system](/docs/technical-details/reference/blob). +- Blob Storage - 4.5 introduces a new [Blob storage system](/docs/reference/blob). - Password Hashing Upgrade - two new password hashing algorithms for better security (to replace md5). - New resource and storage Analytics diff --git a/sidebars.ts b/sidebars.ts index 9acdaded..f70a5d08 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -44,8 +44,8 @@ const sidebars: SidebarsConfig = { }, { type: 'category', - label: 'Technical Details', - items: [{ type: 'autogenerated', dirName: 'technical-details' }], + label: 'Reference', + items: [{ type: 'autogenerated', dirName: 'reference' }], }, ], }; diff --git a/versioned_docs/version-4.2/developers/applications/defining-schemas.md b/versioned_docs/version-4.2/developers/applications/defining-schemas.md index 5c32e20e..17bd7f9a 100644 --- a/versioned_docs/version-4.2/developers/applications/defining-schemas.md +++ b/versioned_docs/version-4.2/developers/applications/defining-schemas.md @@ -83,7 +83,7 @@ The `@updatedTime` directive indicates that this property should be assigned a t ### Defined vs Dynamic Schemas -If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../technical-details/reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. +If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. ### Field Types diff --git a/versioned_docs/version-4.2/developers/applications/index.md b/versioned_docs/version-4.2/developers/applications/index.md index 74288641..a161d960 100644 --- a/versioned_docs/version-4.2/developers/applications/index.md +++ b/versioned_docs/version-4.2/developers/applications/index.md @@ -242,7 +242,7 @@ Now, with an application that you can deploy, update, and re-deploy, you have an ## Custom Functionality with JavaScript -So far we have built an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in HarperDB. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In HarperDB, data is accessed through our [Resource API](../technical-details/reference/resource), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +So far we have built an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in HarperDB. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In HarperDB, data is accessed through our [Resource API](../reference/resource), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: @@ -301,7 +301,7 @@ And a POST request to /CustomDog/ would call this `post` method. The Resource cl The `post` method automatically marks the current instance as being update. However, you can also explicitly specify that you are changing a resource by calling the `update()` method. If you want to modify a resource instance that you retrieved through a `get()` call (like `Breed.get()` call above), you can call its `update()` method to ensure changes are saved (and will be committed in the current transaction). -We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../technical-details/reference/resource) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this: +We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../reference/resource) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this: ```javascript export class CustomDog extends Dog { @@ -341,7 +341,7 @@ Breed.sourcedFrom(BreedSource, { expiration: 3600 }); The [caching documentation](./applications/caching) provides much more information on how to use HarperDB's powerful caching capabilities and set up data sources. -HarperDB provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../technical-details/reference/globals) and the [Resource interface](../technical-details/reference/resource). +HarperDB provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../reference/globals) and the [Resource interface](../reference/resource). ## Configuring Applications/Components diff --git a/versioned_docs/version-4.2/developers/components/writing-extensions.md b/versioned_docs/version-4.2/developers/components/writing-extensions.md index cfdc0a93..1065f613 100644 --- a/versioned_docs/version-4.2/developers/components/writing-extensions.md +++ b/versioned_docs/version-4.2/developers/components/writing-extensions.md @@ -101,7 +101,7 @@ Typically, servers not only communicate with clients, but serve up meaningful da ## Resource Extensions -Resource extensions allow us to handle different files and make them accessible to servers as resources, following the common [Resource API](../../technical-details/reference/resource). To implement a resource extension, you export a function called `handleFile`. Users can then configure which files that should be handled by your extension. For example, if we had implemented an EJS handler, it could be configured as: +Resource extensions allow us to handle different files and make them accessible to servers as resources, following the common [Resource API](../../reference/resource). To implement a resource extension, you export a function called `handleFile`. Users can then configure which files that should be handled by your extension. For example, if we had implemented an EJS handler, it could be configured as: ```yaml module: 'ejs-extension', @@ -129,7 +129,7 @@ Note that these hooks are not mutually exclusive. You can write an extension tha ## Data Source Components -Data source components implement the Resource interface to provide access to various data sources, which may be other APIs, databases, or local storage. Components that implement this interface can then be used as a source for caching tables, can be accessed as part of endpoint implementations, or even used as endpoints themselves. See the [Resource documentation](../../technical-details/reference/resource) for more information on implementing new resources. +Data source components implement the Resource interface to provide access to various data sources, which may be other APIs, databases, or local storage. Components that implement this interface can then be used as a source for caching tables, can be accessed as part of endpoint implementations, or even used as endpoints themselves. See the [Resource documentation](../../reference/resource) for more information on implementing new resources. ## Content Type Extensions diff --git a/versioned_docs/version-4.2/technical-details/_category_.json b/versioned_docs/version-4.2/reference/_category_.json similarity index 54% rename from versioned_docs/version-4.2/technical-details/_category_.json rename to versioned_docs/version-4.2/reference/_category_.json index b965ef06..d6302ac2 100644 --- a/versioned_docs/version-4.2/technical-details/_category_.json +++ b/versioned_docs/version-4.2/reference/_category_.json @@ -1,10 +1,10 @@ { - "label": "Technical Details", + "label": "Reference", "position": 4, "link": { "type": "generated-index", - "title": "Technical Details Documentation", + "title": "Reference Documentation", "description": "Reference documentation and technical specifications", - "keywords": ["technical-details"] + "keywords": ["reference", "specifications"] } } diff --git a/versioned_docs/version-4.2/technical-details/reference/analytics.md b/versioned_docs/version-4.2/reference/analytics.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/analytics.md rename to versioned_docs/version-4.2/reference/analytics.md diff --git a/versioned_docs/version-4.2/technical-details/reference/architecture.md b/versioned_docs/version-4.2/reference/architecture.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/architecture.md rename to versioned_docs/version-4.2/reference/architecture.md diff --git a/versioned_docs/version-4.2/technical-details/reference/content-types.md b/versioned_docs/version-4.2/reference/content-types.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/content-types.md rename to versioned_docs/version-4.2/reference/content-types.md diff --git a/versioned_docs/version-4.2/technical-details/reference/data-types.md b/versioned_docs/version-4.2/reference/data-types.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/data-types.md rename to versioned_docs/version-4.2/reference/data-types.md diff --git a/versioned_docs/version-4.2/technical-details/reference/dynamic-schema.md b/versioned_docs/version-4.2/reference/dynamic-schema.md similarity index 98% rename from versioned_docs/version-4.2/technical-details/reference/dynamic-schema.md rename to versioned_docs/version-4.2/reference/dynamic-schema.md index 843db7a6..ea6ac8cc 100644 --- a/versioned_docs/version-4.2/technical-details/reference/dynamic-schema.md +++ b/versioned_docs/version-4.2/reference/dynamic-schema.md @@ -36,7 +36,7 @@ HarperDB automatically creates two audit attributes used on each record if the t ### Dynamic Schema Example -To better understand the behavior let’s take a look at an example. This example utilizes [HarperDB API operations](../../developers/operations-api/databases-and-tables). +To better understand the behavior let’s take a look at an example. This example utilizes [HarperDB API operations](../developers/operations-api/databases-and-tables). **Create a Database** diff --git a/versioned_docs/version-4.2/technical-details/reference/globals.md b/versioned_docs/version-4.2/reference/globals.md similarity index 86% rename from versioned_docs/version-4.2/technical-details/reference/globals.md rename to versioned_docs/version-4.2/reference/globals.md index e2f5fcd5..535dfddf 100644 --- a/versioned_docs/version-4.2/technical-details/reference/globals.md +++ b/versioned_docs/version-4.2/reference/globals.md @@ -38,7 +38,7 @@ async function getRecord() { } ``` -It is recommended that you [define a schema](../../getting-started/) 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. +It is recommended that you [define a schema](../getting-started/) 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. ### `databases` @@ -59,7 +59,7 @@ This returns the user object with permissions/authorization information based on ### `logger` -This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../../administration/logging/standard-logging) for more information. +This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../administration/logging/standard-logging) for more information. ### `server` @@ -67,7 +67,7 @@ This provides a number of functions and objects to interact with the server incl #### `server.config` -This provides access to the HarperDB configuration object. This comes from the [harperdb-config.yaml](../../deployments/configuration) (parsed into object form). +This provides access to the HarperDB configuration object. This comes from the [harperdb-config.yaml](../deployments/configuration) (parsed into object form). #### `server.recordAnalytics(value, metric, path?, method?, type?)` diff --git a/versioned_docs/version-4.2/technical-details/reference/headers.md b/versioned_docs/version-4.2/reference/headers.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/headers.md rename to versioned_docs/version-4.2/reference/headers.md diff --git a/versioned_docs/version-4.2/technical-details/reference/index.md b/versioned_docs/version-4.2/reference/index.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/index.md rename to versioned_docs/version-4.2/reference/index.md diff --git a/versioned_docs/version-4.2/technical-details/reference/limits.md b/versioned_docs/version-4.2/reference/limits.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/limits.md rename to versioned_docs/version-4.2/reference/limits.md diff --git a/versioned_docs/version-4.2/technical-details/reference/resource.md b/versioned_docs/version-4.2/reference/resource.md similarity index 99% rename from versioned_docs/version-4.2/technical-details/reference/resource.md rename to versioned_docs/version-4.2/reference/resource.md index f28ef8f8..6baec084 100644 --- a/versioned_docs/version-4.2/technical-details/reference/resource.md +++ b/versioned_docs/version-4.2/reference/resource.md @@ -79,7 +79,7 @@ This is the Resource base class. This can be directly extended for custom resour ### `server` -This object provides extension points for extension components that wish to implement new server functionality (new protocols, authentication, etc.). See the [extensions documentation for more information](../../developers/components/writing-extensions). +This object provides extension points for extension components that wish to implement new server functionality (new protocols, authentication, etc.). See the [extensions documentation for more information](../developers/components/writing-extensions). ### `transaction` @@ -87,7 +87,7 @@ This provides a function for starting transactions. See the transactions section ### `contentTypes` -This provides an interface for defining new content type handlers. See the [content type extensions documentation](../../developers/components/writing-extensions) for more information. +This provides an interface for defining new content type handlers. See the [content type extensions documentation](../developers/components/writing-extensions) for more information. ### TypeScript Support diff --git a/versioned_docs/version-4.2/technical-details/reference/storage-algorithm.md b/versioned_docs/version-4.2/reference/storage-algorithm.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/storage-algorithm.md rename to versioned_docs/version-4.2/reference/storage-algorithm.md diff --git a/versioned_docs/version-4.2/technical-details/reference/transactions.md b/versioned_docs/version-4.2/reference/transactions.md similarity index 100% rename from versioned_docs/version-4.2/technical-details/reference/transactions.md rename to versioned_docs/version-4.2/reference/transactions.md diff --git a/versioned_docs/version-4.3/administration/administration.md b/versioned_docs/version-4.3/administration/administration.md index 55afc439..5e4086e3 100644 --- a/versioned_docs/version-4.3/administration/administration.md +++ b/versioned_docs/version-4.3/administration/administration.md @@ -22,7 +22,7 @@ HarperDB provides rapid horizontal scaling capabilities through [node cloning fu HarperDB provides robust capabilities for analytics and observability to facilitate effective and informative monitoring: -- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](../technical-details/reference/analytics). +- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](../reference/analytics). - A large variety of real-time statistics about load, system information, database metrics, thread usage can be retrieved through the [`system_information` API](./developers/operations-api/utilities#system-information). - Information about the current cluster configuration and status can be found in the [cluster APIs](./developers/operations-api/clustering). - Analytics and system information can easily be exported to Prometheus with our [Prometheus exporter component](https://github.com/HarperDB-Add-Ons/prometheus_exporter), making it easy visualize and monitor HarperDB with Graphana. diff --git a/versioned_docs/version-4.3/developers/applications/defining-schemas.md b/versioned_docs/version-4.3/developers/applications/defining-schemas.md index c2c577d6..f45c2de3 100644 --- a/versioned_docs/version-4.3/developers/applications/defining-schemas.md +++ b/versioned_docs/version-4.3/developers/applications/defining-schemas.md @@ -77,7 +77,7 @@ type Brand @table @export { } ``` -Once this is defined we can use the `brand` attribute as a [property in our product instances](../../technical-details/reference/resource) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). +Once this is defined we can use the `brand` attribute as a [property in our product instances](../../reference/resource) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). Again, the foreign key may be a multi-valued array (array of keys referencing the target table records). For example, if we had a list of features that references a Feature table: @@ -136,7 +136,7 @@ The `@updatedTime` directive indicates that this property should be assigned a t ### Defined vs Dynamic Schemas -If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../technical-details/reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. +If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. ### Field Types diff --git a/versioned_docs/version-4.3/developers/applications/index.md b/versioned_docs/version-4.3/developers/applications/index.md index 12fc76cd..a71cf5a8 100644 --- a/versioned_docs/version-4.3/developers/applications/index.md +++ b/versioned_docs/version-4.3/developers/applications/index.md @@ -242,7 +242,7 @@ Now, with an application that you can deploy, update, and re-deploy, you have an ## Custom Functionality with JavaScript -So far we have built an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in HarperDB. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In HarperDB, data is accessed through our [Resource API](../technical-details/reference/resource), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +So far we have built an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in HarperDB. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In HarperDB, data is accessed through our [Resource API](../reference/resource), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: @@ -301,7 +301,7 @@ And a POST request to /CustomDog/ would call this `post` method. The Resource cl The `post` method automatically marks the current instance as being update. However, you can also explicitly specify that you are changing a resource by calling the `update()` method. If you want to modify a resource instance that you retrieved through a `get()` call (like `Breed.get()` call above), you can call its `update()` method to ensure changes are saved (and will be committed in the current transaction). -We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../technical-details/reference/resource) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this: +We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../reference/resource) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this: ```javascript export class CustomDog extends Dog { @@ -341,7 +341,7 @@ Breed.sourcedFrom(BreedSource, { expiration: 3600 }); The [caching documentation](applications/caching) provides much more information on how to use HarperDB's powerful caching capabilities and set up data sources. -HarperDB provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../technical-details/reference/globals) and the [Resource interface](../technical-details/reference/resource). +HarperDB provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../reference/globals) and the [Resource interface](../reference/resource). ## Configuring Applications/Components diff --git a/versioned_docs/version-4.3/developers/components/writing-extensions.md b/versioned_docs/version-4.3/developers/components/writing-extensions.md index 8d2069f8..155cfa5f 100644 --- a/versioned_docs/version-4.3/developers/components/writing-extensions.md +++ b/versioned_docs/version-4.3/developers/components/writing-extensions.md @@ -117,7 +117,7 @@ Typically, servers not only communicate with clients, but serve up meaningful da ## Resource Extensions -Resource extensions allow us to handle different files and make them accessible to servers as resources, following the common [Resource API](../../technical-details/reference/resource). To implement a resource extension, you export a function called `handleFile`. Users can then configure which files that should be handled by your extension. For example, if we had implemented an EJS handler, it could be configured as: +Resource extensions allow us to handle different files and make them accessible to servers as resources, following the common [Resource API](../../reference/resource). To implement a resource extension, you export a function called `handleFile`. Users can then configure which files that should be handled by your extension. For example, if we had implemented an EJS handler, it could be configured as: ```yaml module: 'ejs-extension', @@ -145,7 +145,7 @@ Note that these hooks are not mutually exclusive. You can write an extension tha ## Data Source Components -Data source components implement the `Resource` interface to provide access to various data sources, which may be other APIs, databases, or local storage. Components that implement this interface can then be used as a source for caching tables, can be accessed as part of endpoint implementations, or even used as endpoints themselves. See the [Resource documentation](../../technical-details/reference/resource) for more information on implementing new resources. +Data source components implement the `Resource` interface to provide access to various data sources, which may be other APIs, databases, or local storage. Components that implement this interface can then be used as a source for caching tables, can be accessed as part of endpoint implementations, or even used as endpoints themselves. See the [Resource documentation](../../reference/resource) for more information on implementing new resources. ## Content Type Extensions diff --git a/versioned_docs/version-4.3/technical-details/_category_.json b/versioned_docs/version-4.3/reference/_category_.json similarity index 54% rename from versioned_docs/version-4.3/technical-details/_category_.json rename to versioned_docs/version-4.3/reference/_category_.json index b965ef06..d6302ac2 100644 --- a/versioned_docs/version-4.3/technical-details/_category_.json +++ b/versioned_docs/version-4.3/reference/_category_.json @@ -1,10 +1,10 @@ { - "label": "Technical Details", + "label": "Reference", "position": 4, "link": { "type": "generated-index", - "title": "Technical Details Documentation", + "title": "Reference Documentation", "description": "Reference documentation and technical specifications", - "keywords": ["technical-details"] + "keywords": ["reference", "specifications"] } } diff --git a/versioned_docs/version-4.3/technical-details/reference/analytics.md b/versioned_docs/version-4.3/reference/analytics.md similarity index 100% rename from versioned_docs/version-4.3/technical-details/reference/analytics.md rename to versioned_docs/version-4.3/reference/analytics.md diff --git a/versioned_docs/version-4.3/technical-details/reference/architecture.md b/versioned_docs/version-4.3/reference/architecture.md similarity index 100% rename from versioned_docs/version-4.3/technical-details/reference/architecture.md rename to versioned_docs/version-4.3/reference/architecture.md diff --git a/versioned_docs/version-4.3/technical-details/reference/content-types.md b/versioned_docs/version-4.3/reference/content-types.md similarity index 97% rename from versioned_docs/version-4.3/technical-details/reference/content-types.md rename to versioned_docs/version-4.3/reference/content-types.md index 3311a86b..e94887ad 100644 --- a/versioned_docs/version-4.3/technical-details/reference/content-types.md +++ b/versioned_docs/version-4.3/reference/content-types.md @@ -26,4 +26,4 @@ MessagePack is another efficient binary format like CBOR, with support for all H Comma-separated values is an easy to use and understand format that can be readily imported into spreadsheets or used for data processing. CSV lacks hierarchical structure for most data types, and shouldn't be used for frequent/production use, but when you need it, it is available. -In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../../developers/rest) for more information on how to do this. +In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../developers/rest) for more information on how to do this. diff --git a/versioned_docs/version-4.3/technical-details/reference/data-types.md b/versioned_docs/version-4.3/reference/data-types.md similarity index 92% rename from versioned_docs/version-4.3/technical-details/reference/data-types.md rename to versioned_docs/version-4.3/reference/data-types.md index 1cbfee68..3526a830 100644 --- a/versioned_docs/version-4.3/technical-details/reference/data-types.md +++ b/versioned_docs/version-4.3/reference/data-types.md @@ -4,7 +4,7 @@ title: Data Types # Data Types -HarperDB supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (HarperDB’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. HarperDB supports MessagePack and CBOR, which allows for all of HarperDB supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../../developers/rest)). Available data types include: +HarperDB supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (HarperDB’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. HarperDB supports MessagePack and CBOR, which allows for all of HarperDB supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../developers/rest)). Available data types include: (Note that these labels are descriptive, they do not necessarily correspond to the GraphQL schema type names, but the schema type names are noted where possible) diff --git a/versioned_docs/version-4.3/technical-details/reference/dynamic-schema.md b/versioned_docs/version-4.3/reference/dynamic-schema.md similarity index 98% rename from versioned_docs/version-4.3/technical-details/reference/dynamic-schema.md rename to versioned_docs/version-4.3/reference/dynamic-schema.md index 3bb705a5..02b26b03 100644 --- a/versioned_docs/version-4.3/technical-details/reference/dynamic-schema.md +++ b/versioned_docs/version-4.3/reference/dynamic-schema.md @@ -36,7 +36,7 @@ HarperDB automatically creates two audit attributes used on each record if the t ### Dynamic Schema Example -To better understand the behavior let’s take a look at an example. This example utilizes [HarperDB API operations](../../developers/operations-api/databases-and-tables). +To better understand the behavior let’s take a look at an example. This example utilizes [HarperDB API operations](../developers/operations-api/databases-and-tables). **Create a Database** diff --git a/versioned_docs/version-4.3/technical-details/reference/globals.md b/versioned_docs/version-4.3/reference/globals.md similarity index 94% rename from versioned_docs/version-4.3/technical-details/reference/globals.md rename to versioned_docs/version-4.3/reference/globals.md index 3f6e58dd..2d5f7d10 100644 --- a/versioned_docs/version-4.3/technical-details/reference/globals.md +++ b/versioned_docs/version-4.3/reference/globals.md @@ -38,7 +38,7 @@ async function getRecord() { } ``` -It is recommended that you [define a database](../../getting-started/) 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. +It is recommended that you [define a database](../getting-started/) 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. ## `databases` @@ -59,7 +59,7 @@ This returns the user object with permissions/authorization information based on ## `logger` -This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../../administration/logging/standard-logging) for more information. +This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../administration/logging/standard-logging) for more information. ## `server` @@ -226,7 +226,7 @@ Properties: ### `server.config` -This provides access to the HarperDB configuration object. This comes from the [harperdb-config.yaml](../../deployments/configuration) (parsed into object form). +This provides access to the HarperDB configuration object. This comes from the [harperdb-config.yaml](../deployments/configuration) (parsed into object form). ### `server.recordAnalytics(value, metric, path?, method?, type?)` diff --git a/versioned_docs/version-4.3/technical-details/reference/headers.md b/versioned_docs/version-4.3/reference/headers.md similarity index 100% rename from versioned_docs/version-4.3/technical-details/reference/headers.md rename to versioned_docs/version-4.3/reference/headers.md diff --git a/versioned_docs/version-4.3/technical-details/reference/index.md b/versioned_docs/version-4.3/reference/index.md similarity index 100% rename from versioned_docs/version-4.3/technical-details/reference/index.md rename to versioned_docs/version-4.3/reference/index.md diff --git a/versioned_docs/version-4.3/technical-details/reference/limits.md b/versioned_docs/version-4.3/reference/limits.md similarity index 100% rename from versioned_docs/version-4.3/technical-details/reference/limits.md rename to versioned_docs/version-4.3/reference/limits.md diff --git a/versioned_docs/version-4.3/technical-details/reference/resource.md b/versioned_docs/version-4.3/reference/resource.md similarity index 97% rename from versioned_docs/version-4.3/technical-details/reference/resource.md rename to versioned_docs/version-4.3/reference/resource.md index aee9e298..791d41a8 100644 --- a/versioned_docs/version-4.3/technical-details/reference/resource.md +++ b/versioned_docs/version-4.3/reference/resource.md @@ -95,7 +95,7 @@ This is the Resource base class. This can be directly extended for custom resour ### `server` -This object provides extension points for extension components that wish to implement new server functionality (new protocols, authentication, etc.). See the [extensions documentation for more information](../../developers/components/writing-extensions). +This object provides extension points for extension components that wish to implement new server functionality (new protocols, authentication, etc.). See the [extensions documentation for more information](../developers/components/writing-extensions). ### `transaction` @@ -103,7 +103,7 @@ This provides a function for starting transactions. See the transactions section ### `contentTypes` -This provides an interface for defining new content type handlers. See the [content type extensions documentation](../../developers/components/writing-extensions) for more information. +This provides an interface for defining new content type handlers. See the [content type extensions documentation](../developers/components/writing-extensions) for more information. ### TypeScript Support @@ -271,7 +271,7 @@ When a resource is accessed as a data source: ### `operation(operationObject: Object, authorize?: boolean): Promise` -This method is available on tables and will execute a HarperDB operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../../developers/operations-api) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). +This method is available on tables and will execute a HarperDB operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../developers/operations-api) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). ### `allowStaleWhileRevalidate(entry: { version: number, localTime: number, expiresAt: number, value: object }, id): boolean` @@ -452,7 +452,7 @@ Table.search({ ##### Chained Attributes/Properties -Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../developers/applications/defining-schemas), see the [REST documentation](../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: +Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../developers/applications/defining-schemas) (in addition to the [schema documentation](../developers/applications/defining-schemas), see the [REST documentation](../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: ```javascript Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'HarperDB' }] }); diff --git a/versioned_docs/version-4.3/technical-details/reference/storage-algorithm.md b/versioned_docs/version-4.3/reference/storage-algorithm.md similarity index 100% rename from versioned_docs/version-4.3/technical-details/reference/storage-algorithm.md rename to versioned_docs/version-4.3/reference/storage-algorithm.md diff --git a/versioned_docs/version-4.3/technical-details/reference/transactions.md b/versioned_docs/version-4.3/reference/transactions.md similarity index 100% rename from versioned_docs/version-4.3/technical-details/reference/transactions.md rename to versioned_docs/version-4.3/reference/transactions.md diff --git a/versioned_docs/version-4.4/administration/administration.md b/versioned_docs/version-4.4/administration/administration.md index 070a1ba4..9702927e 100644 --- a/versioned_docs/version-4.4/administration/administration.md +++ b/versioned_docs/version-4.4/administration/administration.md @@ -22,7 +22,7 @@ Harper provides rapid horizontal scaling capabilities through [node cloning func Harper provides robust capabilities for analytics and observability to facilitate effective and informative monitoring: -- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](../technical-details/reference/analytics). +- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](../reference/analytics). - A large variety of real-time statistics about load, system information, database metrics, thread usage can be retrieved through the [`system_information` API](./developers/operations-api/utilities#system-information). - Information about the current cluster configuration and status can be found in the [cluster APIs](./developers/operations-api/clustering). - Analytics and system information can easily be exported to Prometheus with our [Prometheus exporter component](https://github.com/HarperDB-Add-Ons/prometheus_exporter), making it easy visualize and monitor Harper with Graphana. diff --git a/versioned_docs/version-4.4/developers/applications/defining-schemas.md b/versioned_docs/version-4.4/developers/applications/defining-schemas.md index 1af9fcc3..74faddc1 100644 --- a/versioned_docs/version-4.4/developers/applications/defining-schemas.md +++ b/versioned_docs/version-4.4/developers/applications/defining-schemas.md @@ -76,7 +76,7 @@ type Brand @table @export { } ``` -Once this is defined we can use the `brand` attribute as a [property in our product instances](../../technical-details/reference/resource) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). +Once this is defined we can use the `brand` attribute as a [property in our product instances](../../reference/resource) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). Again, the foreign key may be a multi-valued array (array of keys referencing the target table records). For example, if we had a list of features that references a Feature table: @@ -189,7 +189,7 @@ The `@sealed` directive specifies that no additional properties should be allowe ### Defined vs Dynamic Schemas -If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../technical-details/reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. +If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. ### Field Types diff --git a/versioned_docs/version-4.4/developers/applications/index.md b/versioned_docs/version-4.4/developers/applications/index.md index 49dbe7d9..29094048 100644 --- a/versioned_docs/version-4.4/developers/applications/index.md +++ b/versioned_docs/version-4.4/developers/applications/index.md @@ -224,7 +224,7 @@ http://localhost:9926/Dog/?breed=Husky&name=Balto&select=id,name,breed Congratulations, you now have created a secure database application backend with a table, a well-defined structure, access controls, and a functional REST endpoint with query capabilities! See the [REST documentation for more information on HTTP access](../../developers/rest) and see the [Schema reference](applications/defining-schemas) for more options for defining schemas. -> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../../technical-details/reference/graphql). +> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../../reference/graphql). ## Deploying your Application @@ -244,7 +244,7 @@ Now, with an application that you can deploy, update, and re-deploy, you have an ## Custom Functionality with JavaScript -So far we have built an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../technical-details/reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +So far we have built an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: @@ -303,7 +303,7 @@ And a POST request to /CustomDog/ would call this `post` method. The Resource cl The `post` method automatically marks the current instance as being update. However, you can also explicitly specify that you are changing a resource by calling the `update()` method. If you want to modify a resource instance that you retrieved through a `get()` call (like `Breed.get()` call above), you can call its `update()` method to ensure changes are saved (and will be committed in the current transaction). -We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../../technical-details/reference/resources/) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this: +We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../../reference/resources/) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this: ```javascript export class CustomDog extends Dog { @@ -343,7 +343,7 @@ Breed.sourcedFrom(BreedSource, { expiration: 3600 }); The [caching documentation](applications/caching) provides much more information on how to use Harper's powerful caching capabilities and set up data sources. -Harper provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../../technical-details/reference/globals) and the [Resource interface](../../technical-details/reference/resources/). +Harper provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../../reference/globals) and the [Resource interface](../../reference/resources/). ## Configuring Applications/Components diff --git a/versioned_docs/version-4.4/developers/components/built-in.md b/versioned_docs/version-4.4/developers/components/built-in.md index 66ec8e0c..ec5bc80a 100644 --- a/versioned_docs/version-4.4/developers/components/built-in.md +++ b/versioned_docs/version-4.4/developers/components/built-in.md @@ -33,7 +33,7 @@ fastifyRoutes: Enables GraphQL querying via a `/graphql` endpoint loosely implementing the GraphQL Over HTTP specification. -Complete documentation for this feature is available here: [GraphQL](../../technical-details/reference/graphql) +Complete documentation for this feature is available here: [GraphQL](../../reference/graphql) ```yaml graphql: true @@ -56,7 +56,7 @@ graphqlSchema: Specify custom, JavaScript based Harper resources. -Refer to the Application [Custom Functionality with JavaScript](../applications/#custom-functionality-with-javascript) guide, or [Resource Class](../../technical-details/reference/resource) reference documentation for more information on custom resources. +Refer to the Application [Custom Functionality with JavaScript](../applications/#custom-functionality-with-javascript) guide, or [Resource Class](../../reference/resource) reference documentation for more information on custom resources. This component is a [Resource Extension](./reference#resource-extension) and can be configured with the [`files`, `path`, and `root`](./reference#resource-extension-configuration) configuration options. diff --git a/versioned_docs/version-4.4/developers/components/index.md b/versioned_docs/version-4.4/developers/components/index.md index b2539935..9becbe7a 100644 --- a/versioned_docs/version-4.4/developers/components/index.md +++ b/versioned_docs/version-4.4/developers/components/index.md @@ -4,7 +4,7 @@ title: Components # Components -Harper components are a core Harper concept defined as flexible JavaScript based _extensions_ of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../../technical-details/reference/globals) (such as `Resource`, `databases`, and `tables`). +Harper components are a core Harper concept defined as flexible JavaScript based _extensions_ of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../../reference/globals) (such as `Resource`, `databases`, and `tables`). A key aspect to components are their extensibility; components can be built on other components. For example, a [Harper Application](../../developers/applications/) is a component that uses many other components. The [application template](https://github.com/HarperDB/application-template) demonstrates many of Harper's built-in components such as `rest` (for automatic REST endpoint generation), `graphqlSchema` (for table schema definitions), and many more. diff --git a/versioned_docs/version-4.4/developers/components/reference.md b/versioned_docs/version-4.4/developers/components/reference.md index bb041616..525ffa6a 100644 --- a/versioned_docs/version-4.4/developers/components/reference.md +++ b/versioned_docs/version-4.4/developers/components/reference.md @@ -221,7 +221,7 @@ Returns: `boolean | void | Promise` ### Protocol Extension -A Protocol Extension is a more advanced form of a Resource Extension and is mainly used for implementing higher level protocols. For example, the [Harper Next.js Extension](https://github.com/HarperDB/nextjs) handles building and running a Next.js project. A Protocol Extension is particularly useful for adding custom networking handlers (see the [`server`](../../technical-details/reference/globals#server) global API documentation for more information). +A Protocol Extension is a more advanced form of a Resource Extension and is mainly used for implementing higher level protocols. For example, the [Harper Next.js Extension](https://github.com/HarperDB/nextjs) handles building and running a Next.js project. A Protocol Extension is particularly useful for adding custom networking handlers (see the [`server`](../../reference/globals#server) global API documentation for more information). #### Protocol Extension Configuration @@ -237,7 +237,7 @@ For example, the [Harper Next.js Extension](https://github.com/HarperDB/nextjs#o dev: false ``` -Many protocol extensions will use the `port` and `securePort` options for configuring networking handlers. Many of the [`server`](../../technical-details/reference/globals#server) global APIs accept `port` and `securePort` options, so components replicated this for simpler pass-through. +Many protocol extensions will use the `port` and `securePort` options for configuring networking handlers. Many of the [`server`](../../reference/globals#server) global APIs accept `port` and `securePort` options, so components replicated this for simpler pass-through. #### Protocol Extension API diff --git a/versioned_docs/version-4.4/technical-details/_category_.json b/versioned_docs/version-4.4/reference/_category_.json similarity index 54% rename from versioned_docs/version-4.4/technical-details/_category_.json rename to versioned_docs/version-4.4/reference/_category_.json index b965ef06..d6302ac2 100644 --- a/versioned_docs/version-4.4/technical-details/_category_.json +++ b/versioned_docs/version-4.4/reference/_category_.json @@ -1,10 +1,10 @@ { - "label": "Technical Details", + "label": "Reference", "position": 4, "link": { "type": "generated-index", - "title": "Technical Details Documentation", + "title": "Reference Documentation", "description": "Reference documentation and technical specifications", - "keywords": ["technical-details"] + "keywords": ["reference", "specifications"] } } diff --git a/versioned_docs/version-4.4/technical-details/reference/analytics.md b/versioned_docs/version-4.4/reference/analytics.md similarity index 100% rename from versioned_docs/version-4.4/technical-details/reference/analytics.md rename to versioned_docs/version-4.4/reference/analytics.md diff --git a/versioned_docs/version-4.4/technical-details/reference/architecture.md b/versioned_docs/version-4.4/reference/architecture.md similarity index 100% rename from versioned_docs/version-4.4/technical-details/reference/architecture.md rename to versioned_docs/version-4.4/reference/architecture.md diff --git a/versioned_docs/version-4.6/technical-details/reference/content-types.md b/versioned_docs/version-4.4/reference/content-types.md similarity index 98% rename from versioned_docs/version-4.6/technical-details/reference/content-types.md rename to versioned_docs/version-4.4/reference/content-types.md index 8d0feaf3..b7d223f4 100644 --- a/versioned_docs/version-4.6/technical-details/reference/content-types.md +++ b/versioned_docs/version-4.4/reference/content-types.md @@ -32,4 +32,4 @@ MessagePack is another efficient binary format like CBOR, with support for all H Comma-separated values is an easy to use and understand format that can be readily imported into spreadsheets or used for data processing. CSV lacks hierarchical structure for most data types, and shouldn't be used for frequent/production use, but when you need it, it is available. -In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../../developers/rest) for more information on how to do this. +In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../developers/rest) for more information on how to do this. diff --git a/versioned_docs/version-4.4/technical-details/reference/data-types.md b/versioned_docs/version-4.4/reference/data-types.md similarity index 92% rename from versioned_docs/version-4.4/technical-details/reference/data-types.md rename to versioned_docs/version-4.4/reference/data-types.md index 50705400..9f7d3e79 100644 --- a/versioned_docs/version-4.4/technical-details/reference/data-types.md +++ b/versioned_docs/version-4.4/reference/data-types.md @@ -4,7 +4,7 @@ title: Data Types # Data Types -Harper supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (Harper’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. Harper supports MessagePack and CBOR, which allows for all of Harper supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../../developers/rest)). Available data types include: +Harper supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (Harper’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. Harper supports MessagePack and CBOR, which allows for all of Harper supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../developers/rest)). Available data types include: (Note that these labels are descriptive, they do not necessarily correspond to the GraphQL schema type names, but the schema type names are noted where possible) diff --git a/versioned_docs/version-4.4/technical-details/reference/dynamic-schema.md b/versioned_docs/version-4.4/reference/dynamic-schema.md similarity index 98% rename from versioned_docs/version-4.4/technical-details/reference/dynamic-schema.md rename to versioned_docs/version-4.4/reference/dynamic-schema.md index 2141ee36..5585f9cd 100644 --- a/versioned_docs/version-4.4/technical-details/reference/dynamic-schema.md +++ b/versioned_docs/version-4.4/reference/dynamic-schema.md @@ -36,7 +36,7 @@ Harper automatically creates two audit attributes used on each record if the tab ### Dynamic Schema Example -To better understand the behavior let’s take a look at an example. This example utilizes [Harper API operations](../../developers/operations-api/databases-and-tables). +To better understand the behavior let’s take a look at an example. This example utilizes [Harper API operations](../developers/operations-api/databases-and-tables). **Create a Database** diff --git a/versioned_docs/version-4.4/technical-details/reference/globals.md b/versioned_docs/version-4.4/reference/globals.md similarity index 96% rename from versioned_docs/version-4.4/technical-details/reference/globals.md rename to versioned_docs/version-4.4/reference/globals.md index dc7bd1f0..d8158e96 100644 --- a/versioned_docs/version-4.4/technical-details/reference/globals.md +++ b/versioned_docs/version-4.4/reference/globals.md @@ -38,7 +38,7 @@ async function getRecord() { } ``` -It is recommended that you [define a database](../../getting-started) 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. +It is recommended that you [define a database](../getting-started) 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. ## `databases` @@ -59,7 +59,7 @@ This returns the user object with permissions/authorization information based on ## `logger` -This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../../administration/logging/standard-logging) for more information. +This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../administration/logging/standard-logging) for more information. ## `server` @@ -244,7 +244,7 @@ Properties: ### `server.config` -This provides access to the Harper configuration object. This comes from the [harperdb-config.yaml](../../deployments/configuration) (parsed into object form). +This provides access to the Harper configuration object. This comes from the [harperdb-config.yaml](../deployments/configuration) (parsed into object form). ### `server.recordAnalytics(value, metric, path?, method?, type?)` diff --git a/versioned_docs/version-4.4/technical-details/reference/graphql.md b/versioned_docs/version-4.4/reference/graphql.md similarity index 98% rename from versioned_docs/version-4.4/technical-details/reference/graphql.md rename to versioned_docs/version-4.4/reference/graphql.md index d2c282fa..4c429853 100644 --- a/versioned_docs/version-4.4/technical-details/reference/graphql.md +++ b/versioned_docs/version-4.4/reference/graphql.md @@ -4,7 +4,7 @@ title: GraphQL Querying # GraphQL Querying -Harper supports GraphQL in a variety of ways. It can be used for [defining schemas](../../developers/applications/defining-schemas), and for querying [Resources](./resource). +Harper supports GraphQL in a variety of ways. It can be used for [defining schemas](../developers/applications/defining-schemas), and for querying [Resources](./resource). Get started by setting `graphql: true` in `config.yaml`. diff --git a/versioned_docs/version-4.4/technical-details/reference/headers.md b/versioned_docs/version-4.4/reference/headers.md similarity index 100% rename from versioned_docs/version-4.4/technical-details/reference/headers.md rename to versioned_docs/version-4.4/reference/headers.md diff --git a/versioned_docs/version-4.4/technical-details/reference/index.md b/versioned_docs/version-4.4/reference/index.md similarity index 100% rename from versioned_docs/version-4.4/technical-details/reference/index.md rename to versioned_docs/version-4.4/reference/index.md diff --git a/versioned_docs/version-4.4/technical-details/reference/limits.md b/versioned_docs/version-4.4/reference/limits.md similarity index 100% rename from versioned_docs/version-4.4/technical-details/reference/limits.md rename to versioned_docs/version-4.4/reference/limits.md diff --git a/versioned_docs/version-4.4/technical-details/reference/resource.md b/versioned_docs/version-4.4/reference/resource.md similarity index 97% rename from versioned_docs/version-4.4/technical-details/reference/resource.md rename to versioned_docs/version-4.4/reference/resource.md index 0f7980d7..c981318e 100644 --- a/versioned_docs/version-4.4/technical-details/reference/resource.md +++ b/versioned_docs/version-4.4/reference/resource.md @@ -97,7 +97,7 @@ This is the Resource base class. This can be directly extended for custom resour ### `server` -This object provides extension points for extension components that wish to implement new server functionality (new protocols, authentication, etc.). See the [extensions documentation for more information](../../developers/components/reference#extensions). +This object provides extension points for extension components that wish to implement new server functionality (new protocols, authentication, etc.). See the [extensions documentation for more information](../developers/components/reference#extensions). ### `transaction` @@ -280,7 +280,7 @@ When a resource is accessed as a data source: ### `operation(operationObject: Object, authorize?: boolean): Promise` -This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). +This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). ### `allowStaleWhileRevalidate(entry: { version: number, localTime: number, expiresAt: number, value: object }, id): boolean` @@ -387,7 +387,7 @@ type MyTable @table { } ``` -See the [schema documentation](../../developers/applications/defining-schemas) for more information on computed attributes. +See the [schema documentation](../developers/applications/defining-schemas) for more information on computed attributes. ### `primaryKey` @@ -482,7 +482,7 @@ Table.search({ **Chained Attributes/Properties** -Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../developers/applications/defining-schemas), see the [REST documentation](../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: +Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../developers/applications/defining-schemas) (in addition to the [schema documentation](../developers/applications/defining-schemas), see the [REST documentation](../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: ```javascript Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] }); diff --git a/versioned_docs/version-4.4/technical-details/reference/storage-algorithm.md b/versioned_docs/version-4.4/reference/storage-algorithm.md similarity index 100% rename from versioned_docs/version-4.4/technical-details/reference/storage-algorithm.md rename to versioned_docs/version-4.4/reference/storage-algorithm.md diff --git a/versioned_docs/version-4.4/technical-details/reference/transactions.md b/versioned_docs/version-4.4/reference/transactions.md similarity index 100% rename from versioned_docs/version-4.4/technical-details/reference/transactions.md rename to versioned_docs/version-4.4/reference/transactions.md diff --git a/versioned_docs/version-4.5/administration/administration.md b/versioned_docs/version-4.5/administration/administration.md index 90ef23f1..9857b704 100644 --- a/versioned_docs/version-4.5/administration/administration.md +++ b/versioned_docs/version-4.5/administration/administration.md @@ -22,7 +22,7 @@ Harper provides rapid horizontal scaling capabilities through node cloning funct Harper provides robust capabilities for analytics and observability to facilitate effective and informative monitoring: -- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](../technical-details/reference/analytics). +- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](../reference/analytics). - A large variety of real-time statistics about load, system information, database metrics, thread usage can be retrieved through the [`system_information` API](../developers/operations-api/system-operations). - Information about the current cluster configuration and status can be found in the [cluster APIs](../developers/operations-api/clustering). - Analytics and system information can easily be exported to Prometheus with our [Prometheus exporter component](https://github.com/HarperDB-Add-Ons/prometheus_exporter), making it easy visualize and monitor Harper with Graphana. diff --git a/versioned_docs/version-4.5/developers/applications/defining-schemas.md b/versioned_docs/version-4.5/developers/applications/defining-schemas.md index e1c16f18..b57dfe51 100644 --- a/versioned_docs/version-4.5/developers/applications/defining-schemas.md +++ b/versioned_docs/version-4.5/developers/applications/defining-schemas.md @@ -78,7 +78,7 @@ type Brand @table @export { } ``` -Once this is defined we can use the `brand` attribute as a [property in our product instances](../../technical-details/reference/resource) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). +Once this is defined we can use the `brand` attribute as a [property in our product instances](../../reference/resource) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). Again, the foreign key may be a multi-valued array (array of keys referencing the target table records). For example, if we had a list of features that references a Feature table: @@ -191,7 +191,7 @@ The `@sealed` directive specifies that no additional properties should be allowe ### Defined vs Dynamic Schemas -If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../technical-details/reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. +If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. ### Field Types @@ -207,7 +207,7 @@ Harper supports the following field types in addition to user defined (object) t - `Any`: Any primitive, object, or array is allowed - `Date`: A Date object - `Bytes`: Binary data as a Buffer or Uint8Array -- `Blob`: Binary data as a [Blob](../../technical-details/reference/blob), designed for large blocks of data that can be streamed. It is recommend that you use this for binary data that will typically be larger than 20KB. +- `Blob`: Binary data as a [Blob](../../reference/blob), designed for large blocks of data that can be streamed. It is recommend that you use this for binary data that will typically be larger than 20KB. #### Renaming Tables diff --git a/versioned_docs/version-4.5/developers/applications/index.md b/versioned_docs/version-4.5/developers/applications/index.md index e0e3ae3b..4c36b35b 100644 --- a/versioned_docs/version-4.5/developers/applications/index.md +++ b/versioned_docs/version-4.5/developers/applications/index.md @@ -34,7 +34,7 @@ flowchart LR ## Custom Functionality with JavaScript -[The getting started guide](../../getting-started/first-harper-app) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../technical-details/reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +[The getting started guide](../../getting-started/first-harper-app) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: @@ -93,7 +93,7 @@ And a POST request to /CustomDog/ would call this `post` method. The Resource cl The `post` method automatically marks the current instance as being update. However, you can also explicitly specify that you are changing a resource by calling the `update()` method. If you want to modify a resource instance that you retrieved through a `get()` call (like `Breed.get()` call above), you can call its `update()` method to ensure changes are saved (and will be committed in the current transaction). -We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../../technical-details/reference/resources/) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this: +We can also define custom authorization capabilities. For example, we might want to specify that only the owner of a dog can make updates to a dog. We could add logic to our `post` method or `put` method to do this, but we may want to separate the logic so these methods can be called separately without authorization checks. The [Resource API](../../reference/resources/) defines `allowRead`, `allowUpdate`, `allowCreate`, and `allowDelete`, or to easily configure individual capabilities. For example, we might do this: ```javascript export class CustomDog extends Dog { @@ -133,7 +133,7 @@ Breed.sourcedFrom(BreedSource, { expiration: 3600 }); The [caching documentation](applications/caching) provides much more information on how to use Harper's powerful caching capabilities and set up data sources. -Harper provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../../technical-details/reference/globals) and the [Resource interface](../../technical-details/reference/resources/). +Harper provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../../reference/globals) and the [Resource interface](../../reference/resources/). ## Configuring Applications/Components diff --git a/versioned_docs/version-4.5/developers/components/built-in.md b/versioned_docs/version-4.5/developers/components/built-in.md index 6eee3879..b7f4498e 100644 --- a/versioned_docs/version-4.5/developers/components/built-in.md +++ b/versioned_docs/version-4.5/developers/components/built-in.md @@ -39,7 +39,7 @@ fastifyRoutes: Enables GraphQL querying via a `/graphql` endpoint loosely implementing the GraphQL Over HTTP specification. -Complete documentation for this feature is available here: [GraphQL](../../technical-details/reference/graphql) +Complete documentation for this feature is available here: [GraphQL](../../reference/graphql) ```yaml graphql: true @@ -62,7 +62,7 @@ graphqlSchema: Specify custom, JavaScript based Harper resources. -Refer to the Application [Custom Functionality with JavaScript](../applications/#custom-functionality-with-javascript) guide, or [Resource Class](../../technical-details/reference/resource) reference documentation for more information on custom resources. +Refer to the Application [Custom Functionality with JavaScript](../applications/#custom-functionality-with-javascript) guide, or [Resource Class](../../reference/resource) reference documentation for more information on custom resources. This component is a [Resource Extension](./reference#resource-extension) and can be configured with the [`files`, `path`, and `root`](./reference#resource-extension-configuration) configuration options. diff --git a/versioned_docs/version-4.5/developers/components/index.md b/versioned_docs/version-4.5/developers/components/index.md index f04fe5fe..9a5609dc 100644 --- a/versioned_docs/version-4.5/developers/components/index.md +++ b/versioned_docs/version-4.5/developers/components/index.md @@ -4,7 +4,7 @@ title: Components # Components -Harper components are a core Harper concept defined as flexible JavaScript based _extensions_ of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../../technical-details/reference/globals) (such as `Resource`, `databases`, and `tables`). +Harper components are a core Harper concept defined as flexible JavaScript based _extensions_ of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../../reference/globals) (such as `Resource`, `databases`, and `tables`). A key aspect to components are their extensibility; components can be built on other components. For example, a [Harper Application](../../developers/applications) is a component that uses many other components. The [application template](https://github.com/HarperDB/application-template) demonstrates many of Harper's built-in components such as `rest` (for automatic REST endpoint generation), `graphqlSchema` (for table schema definitions), and many more. diff --git a/versioned_docs/version-4.5/developers/components/reference.md b/versioned_docs/version-4.5/developers/components/reference.md index bb041616..525ffa6a 100644 --- a/versioned_docs/version-4.5/developers/components/reference.md +++ b/versioned_docs/version-4.5/developers/components/reference.md @@ -221,7 +221,7 @@ Returns: `boolean | void | Promise` ### Protocol Extension -A Protocol Extension is a more advanced form of a Resource Extension and is mainly used for implementing higher level protocols. For example, the [Harper Next.js Extension](https://github.com/HarperDB/nextjs) handles building and running a Next.js project. A Protocol Extension is particularly useful for adding custom networking handlers (see the [`server`](../../technical-details/reference/globals#server) global API documentation for more information). +A Protocol Extension is a more advanced form of a Resource Extension and is mainly used for implementing higher level protocols. For example, the [Harper Next.js Extension](https://github.com/HarperDB/nextjs) handles building and running a Next.js project. A Protocol Extension is particularly useful for adding custom networking handlers (see the [`server`](../../reference/globals#server) global API documentation for more information). #### Protocol Extension Configuration @@ -237,7 +237,7 @@ For example, the [Harper Next.js Extension](https://github.com/HarperDB/nextjs#o dev: false ``` -Many protocol extensions will use the `port` and `securePort` options for configuring networking handlers. Many of the [`server`](../../technical-details/reference/globals#server) global APIs accept `port` and `securePort` options, so components replicated this for simpler pass-through. +Many protocol extensions will use the `port` and `securePort` options for configuring networking handlers. Many of the [`server`](../../reference/globals#server) global APIs accept `port` and `securePort` options, so components replicated this for simpler pass-through. #### Protocol Extension API diff --git a/versioned_docs/version-4.5/getting-started/first-harper-app.md b/versioned_docs/version-4.5/getting-started/first-harper-app.md index 541d674e..f8090b56 100644 --- a/versioned_docs/version-4.5/getting-started/first-harper-app.md +++ b/versioned_docs/version-4.5/getting-started/first-harper-app.md @@ -163,7 +163,7 @@ http://localhost:9926/Dog/?breed=Husky&name=Balto&select(id,name,breed) Congratulations, you now have created a secure database application backend with a table, a well-defined structure, access controls, and a functional REST endpoint with query capabilities! See the [REST documentation for more information on HTTP access](../developers/rest) and see the [Schema reference](../developers/applications/defining-schemas) for more options for defining schemas. -> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../../technical-details/reference/graphql). +> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../../reference/graphql). ## Key Takeaway diff --git a/versioned_docs/version-4.5/getting-started/harper-concepts.md b/versioned_docs/version-4.5/getting-started/harper-concepts.md index bfa34f20..46f07cee 100644 --- a/versioned_docs/version-4.5/getting-started/harper-concepts.md +++ b/versioned_docs/version-4.5/getting-started/harper-concepts.md @@ -8,7 +8,7 @@ As you begin your journey with Harper, there are a few concepts and definitions ## Components -Harper components are a core Harper concept defined as flexible JavaScript based extensions of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../technical-details/reference/globals) (such as Resource, databases, and tables). +Harper components are a core Harper concept defined as flexible JavaScript based extensions of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../reference/globals) (such as Resource, databases, and tables). A key aspect to components are their extensibility; components can be built on other components. For example, a [Harper Application](../developers/applications) is a component that uses many other components. The [application template](https://github.com/HarperDB/application-template) demonstrates many of Harper's built-in components such as [rest](../developers/components/built-in#rest) (for automatic REST endpoint generation), [graphqlSchema](../developers/components/built-in#graphqlschema) (for table schema definitions), and many more. diff --git a/versioned_docs/version-4.5/reference/_category_.json b/versioned_docs/version-4.5/reference/_category_.json new file mode 100644 index 00000000..d6302ac2 --- /dev/null +++ b/versioned_docs/version-4.5/reference/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Reference", + "position": 4, + "link": { + "type": "generated-index", + "title": "Reference Documentation", + "description": "Reference documentation and technical specifications", + "keywords": ["reference", "specifications"] + } +} diff --git a/versioned_docs/version-4.5/technical-details/reference/analytics.md b/versioned_docs/version-4.5/reference/analytics.md similarity index 100% rename from versioned_docs/version-4.5/technical-details/reference/analytics.md rename to versioned_docs/version-4.5/reference/analytics.md diff --git a/versioned_docs/version-4.5/technical-details/reference/architecture.md b/versioned_docs/version-4.5/reference/architecture.md similarity index 100% rename from versioned_docs/version-4.5/technical-details/reference/architecture.md rename to versioned_docs/version-4.5/reference/architecture.md diff --git a/docs/technical-details/reference/blob.md b/versioned_docs/version-4.5/reference/blob.md similarity index 97% rename from docs/technical-details/reference/blob.md rename to versioned_docs/version-4.5/reference/blob.md index a62ba2eb..9b6b1fb2 100644 --- a/docs/technical-details/reference/blob.md +++ b/versioned_docs/version-4.5/reference/blob.md @@ -103,4 +103,4 @@ if (blob.size === undefined) { ``` -See the [configuration](../../deployments/configuration) documentation for more information on configuring where blob are stored. +See the [configuration](../deployments/configuration) documentation for more information on configuring where blob are stored. diff --git a/versioned_docs/version-4.5/technical-details/reference/content-types.md b/versioned_docs/version-4.5/reference/content-types.md similarity index 98% rename from versioned_docs/version-4.5/technical-details/reference/content-types.md rename to versioned_docs/version-4.5/reference/content-types.md index 8d0feaf3..b7d223f4 100644 --- a/versioned_docs/version-4.5/technical-details/reference/content-types.md +++ b/versioned_docs/version-4.5/reference/content-types.md @@ -32,4 +32,4 @@ MessagePack is another efficient binary format like CBOR, with support for all H Comma-separated values is an easy to use and understand format that can be readily imported into spreadsheets or used for data processing. CSV lacks hierarchical structure for most data types, and shouldn't be used for frequent/production use, but when you need it, it is available. -In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../../developers/rest) for more information on how to do this. +In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../developers/rest) for more information on how to do this. diff --git a/versioned_docs/version-4.5/technical-details/reference/data-types.md b/versioned_docs/version-4.5/reference/data-types.md similarity index 93% rename from versioned_docs/version-4.5/technical-details/reference/data-types.md rename to versioned_docs/version-4.5/reference/data-types.md index 1591a6a5..8dd902e6 100644 --- a/versioned_docs/version-4.5/technical-details/reference/data-types.md +++ b/versioned_docs/version-4.5/reference/data-types.md @@ -4,7 +4,7 @@ title: Data Types # Data Types -Harper supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (Harper’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. Harper supports MessagePack and CBOR, which allows for all of Harper supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../../developers/rest)). Available data types include: +Harper supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (Harper’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. Harper supports MessagePack and CBOR, which allows for all of Harper supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../developers/rest)). Available data types include: (Note that these labels are descriptive, they do not necessarily correspond to the GraphQL schema type names, but the schema type names are noted where possible) diff --git a/versioned_docs/version-4.5/technical-details/reference/dynamic-schema.md b/versioned_docs/version-4.5/reference/dynamic-schema.md similarity index 98% rename from versioned_docs/version-4.5/technical-details/reference/dynamic-schema.md rename to versioned_docs/version-4.5/reference/dynamic-schema.md index 986c8b44..3c44d5af 100644 --- a/versioned_docs/version-4.5/technical-details/reference/dynamic-schema.md +++ b/versioned_docs/version-4.5/reference/dynamic-schema.md @@ -36,7 +36,7 @@ Harper automatically creates two audit attributes used on each record if the tab ### Dynamic Schema Example -To better understand the behavior let’s take a look at an example. This example utilizes [Harper API operations](../../developers/operations-api/databases-and-tables). +To better understand the behavior let’s take a look at an example. This example utilizes [Harper API operations](../developers/operations-api/databases-and-tables). **Create a Database** diff --git a/versioned_docs/version-4.5/technical-details/reference/globals.md b/versioned_docs/version-4.5/reference/globals.md similarity index 97% rename from versioned_docs/version-4.5/technical-details/reference/globals.md rename to versioned_docs/version-4.5/reference/globals.md index 0118882d..1d3acd95 100644 --- a/versioned_docs/version-4.5/technical-details/reference/globals.md +++ b/versioned_docs/version-4.5/reference/globals.md @@ -38,7 +38,7 @@ async function getRecord() { } ``` -It is recommended that you [define a database](../../getting-started) 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. +It is recommended that you [define a database](../getting-started) 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. ## `databases` @@ -59,7 +59,7 @@ This returns the user object with permissions/authorization information based on ## `logger` -This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../../administration/logging/standard-logging) for more information. +This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../administration/logging/standard-logging) for more information. ## `server` @@ -257,7 +257,7 @@ Properties: ### `server.config` -This provides access to the Harper configuration object. This comes from the [harperdb-config.yaml](../../deployments/configuration) (parsed into object form). +This provides access to the Harper configuration object. This comes from the [harperdb-config.yaml](../deployments/configuration) (parsed into object form). ### `server.recordAnalytics(value, metric, path?, method?, type?)` diff --git a/versioned_docs/version-4.5/technical-details/reference/graphql.md b/versioned_docs/version-4.5/reference/graphql.md similarity index 98% rename from versioned_docs/version-4.5/technical-details/reference/graphql.md rename to versioned_docs/version-4.5/reference/graphql.md index ea0bc0aa..2dc0093d 100644 --- a/versioned_docs/version-4.5/technical-details/reference/graphql.md +++ b/versioned_docs/version-4.5/reference/graphql.md @@ -4,7 +4,7 @@ title: GraphQL Querying # GraphQL Querying -Harper supports GraphQL in a variety of ways. It can be used for [defining schemas](../../developers/applications/defining-schemas), and for querying [Resources](./resource). +Harper supports GraphQL in a variety of ways. It can be used for [defining schemas](../developers/applications/defining-schemas), and for querying [Resources](./resource). Get started by setting `graphql: true` in `config.yaml`. diff --git a/versioned_docs/version-4.5/technical-details/reference/headers.md b/versioned_docs/version-4.5/reference/headers.md similarity index 100% rename from versioned_docs/version-4.5/technical-details/reference/headers.md rename to versioned_docs/version-4.5/reference/headers.md diff --git a/versioned_docs/version-4.5/technical-details/reference/index.md b/versioned_docs/version-4.5/reference/index.md similarity index 100% rename from versioned_docs/version-4.5/technical-details/reference/index.md rename to versioned_docs/version-4.5/reference/index.md diff --git a/versioned_docs/version-4.5/technical-details/reference/limits.md b/versioned_docs/version-4.5/reference/limits.md similarity index 100% rename from versioned_docs/version-4.5/technical-details/reference/limits.md rename to versioned_docs/version-4.5/reference/limits.md diff --git a/versioned_docs/version-4.5/technical-details/reference/resource.md b/versioned_docs/version-4.5/reference/resource.md similarity index 97% rename from versioned_docs/version-4.5/technical-details/reference/resource.md rename to versioned_docs/version-4.5/reference/resource.md index 2a805df8..f21b1d77 100644 --- a/versioned_docs/version-4.5/technical-details/reference/resource.md +++ b/versioned_docs/version-4.5/reference/resource.md @@ -97,7 +97,7 @@ This is the Resource base class. This can be directly extended for custom resour ### `server` -This object provides extension points for extension components that wish to implement new server functionality (new protocols, authentication, etc.). See the [extensions documentation for more information](../../developers/components/reference#extensions). +This object provides extension points for extension components that wish to implement new server functionality (new protocols, authentication, etc.). See the [extensions documentation for more information](../developers/components/reference#extensions). ### `transaction` @@ -275,7 +275,7 @@ When a resource is accessed as a data source: ### `operation(operationObject: Object, authorize?: boolean): Promise` -This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). +This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). ### `allowStaleWhileRevalidate(entry: { version: number, localTime: number, expiresAt: number, value: object }, id): boolean` @@ -382,7 +382,7 @@ type MyTable @table { } ``` -See the [schema documentation](../../developers/applications/defining-schemas) for more information on computed attributes. +See the [schema documentation](../developers/applications/defining-schemas) for more information on computed attributes. ### `primaryKey` @@ -499,7 +499,7 @@ Table.search({ **Chained Attributes/Properties** -Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../developers/applications/defining-schemas), see the [REST documentation](../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: +Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../developers/applications/defining-schemas) (in addition to the [schema documentation](../developers/applications/defining-schemas), see the [REST documentation](../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: ```javascript Product.search({ conditions: [`{ attribute: ['brand', 'name'], value: 'Harper' }`] }); diff --git a/versioned_docs/version-4.5/technical-details/reference/storage-algorithm.md b/versioned_docs/version-4.5/reference/storage-algorithm.md similarity index 100% rename from versioned_docs/version-4.5/technical-details/reference/storage-algorithm.md rename to versioned_docs/version-4.5/reference/storage-algorithm.md diff --git a/versioned_docs/version-4.5/technical-details/reference/transactions.md b/versioned_docs/version-4.5/reference/transactions.md similarity index 100% rename from versioned_docs/version-4.5/technical-details/reference/transactions.md rename to versioned_docs/version-4.5/reference/transactions.md diff --git a/versioned_docs/version-4.5/technical-details/_category_.json b/versioned_docs/version-4.5/technical-details/_category_.json deleted file mode 100644 index b965ef06..00000000 --- a/versioned_docs/version-4.5/technical-details/_category_.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "label": "Technical Details", - "position": 4, - "link": { - "type": "generated-index", - "title": "Technical Details Documentation", - "description": "Reference documentation and technical specifications", - "keywords": ["technical-details"] - } -} diff --git a/versioned_docs/version-4.6/administration/administration.md b/versioned_docs/version-4.6/administration/administration.md index 8c464e6a..e0084bb5 100644 --- a/versioned_docs/version-4.6/administration/administration.md +++ b/versioned_docs/version-4.6/administration/administration.md @@ -22,7 +22,7 @@ Harper provides rapid horizontal scaling capabilities through [node cloning func Harper provides robust capabilities for analytics and observability to facilitate effective and informative monitoring: -- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](./technical-details/reference/analytics). +- Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](./reference/analytics). - A large variety of real-time statistics about load, system information, database metrics, thread usage can be retrieved through the [`system_information` API](./developers/operations-api/system-operations). - Information about the current cluster configuration and status can be found in the [cluster APIs](./developers/operations-api/clustering). - Analytics and system information can easily be exported to Prometheus with our [Prometheus exporter component](https://github.com/HarperDB-Add-Ons/prometheus_exporter), making it easy visualize and monitor Harper with Graphana. diff --git a/versioned_docs/version-4.6/deployments/configuration.md b/versioned_docs/version-4.6/deployments/configuration.md index 25cdcb02..8d6e9641 100644 --- a/versioned_docs/version-4.6/deployments/configuration.md +++ b/versioned_docs/version-4.6/deployments/configuration.md @@ -690,7 +690,7 @@ Harper's logger supports defining multiple logging configurations for different `logging.external` -The `logging.external` section can be used to define logging for all external components that use the [`logger` API](../technical-details/reference/globals). For example: +The `logging.external` section can be used to define logging for all external components that use the [`logger` API](../reference/globals). For example: ```yaml logging: @@ -1196,7 +1196,7 @@ The name of the component. This will be used to name the folder where the compon `package` - _Type_: string -A reference to your [component](../technical-details/reference/components/applications#adding-components-to-root) package. This could be a remote git repo, a local folder/file or an NPM package. Harper will add this package to a package.json file and call `npm install` on it, so any reference that works with that paradigm will work here. +A reference to your [component](../reference/components/applications#adding-components-to-root) package. This could be a remote git repo, a local folder/file or an NPM package. Harper will add this package to a package.json file and call `npm install` on it, so any reference that works with that paradigm will work here. Read more about npm install [here](https://docs.npmjs.com/cli/v8/commands/npm-install) diff --git a/versioned_docs/version-4.6/developers/applications/data-loader.md b/versioned_docs/version-4.6/developers/applications/data-loader.md index 9aed9546..ba9f433c 100644 --- a/versioned_docs/version-4.6/developers/applications/data-loader.md +++ b/versioned_docs/version-4.6/developers/applications/data-loader.md @@ -15,7 +15,7 @@ dataLoader: files: 'data/*.json' ``` -The Data Loader is an [Extension](../../technical-details/reference/components#extensions) and supports the standard `files` configuration option. +The Data Loader is an [Extension](../../reference/components#extensions) and supports the standard `files` configuration option. ## Data File Format @@ -176,6 +176,6 @@ rest: true ## Related Documentation -- [Built-In Components](../../technical-details/reference/components/built-in-extensions) -- [Extensions](../../technical-details/reference/components/extensions) +- [Built-In Components](../../reference/components/built-in-extensions) +- [Extensions](../../reference/components/extensions) - [Bulk Operations](../operations-api/bulk-operations) - For loading data via the Operations API diff --git a/versioned_docs/version-4.6/developers/applications/defining-schemas.md b/versioned_docs/version-4.6/developers/applications/defining-schemas.md index df239ca5..9df28255 100644 --- a/versioned_docs/version-4.6/developers/applications/defining-schemas.md +++ b/versioned_docs/version-4.6/developers/applications/defining-schemas.md @@ -78,7 +78,7 @@ type Brand @table @export { } ``` -Once this is defined we can use the `brand` attribute as a [property in our product instances](../../technical-details/reference/resources/) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). +Once this is defined we can use the `brand` attribute as a [property in our product instances](../../reference/resources/) and allow for querying by `brand` and selecting brand attributes as returned properties in [query results](../rest). Again, the foreign key may be a multi-valued array (array of keys referencing the target table records). For example, if we had a list of features that references a Feature table: @@ -241,7 +241,7 @@ The `@sealed` directive specifies that no additional properties should be allowe ### Defined vs Dynamic Schemas -If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../technical-details/reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. +If you do not define a schema for a table and create a table through the operations API (without specifying attributes) or studio, such a table will not have a defined schema and will follow the behavior of a ["dynamic-schema" table](../../reference/dynamic-schema). It is generally best-practice to define schemas for your tables to ensure predictable, consistent structures with data integrity. ### Field Types @@ -257,7 +257,7 @@ Harper supports the following field types in addition to user defined (object) t - `Any`: Any primitive, object, or array is allowed - `Date`: A Date object - `Bytes`: Binary data as a Buffer or Uint8Array -- `Blob`: Binary data as a [Blob](../../technical-details/reference/blob), designed for large blocks of data that can be streamed. It is recommend that you use this for binary data that will typically be larger than 20KB. +- `Blob`: Binary data as a [Blob](../../reference/blob), designed for large blocks of data that can be streamed. It is recommend that you use this for binary data that will typically be larger than 20KB. #### Renaming Tables diff --git a/versioned_docs/version-4.6/developers/applications/index.md b/versioned_docs/version-4.6/developers/applications/index.md index 72b4c2c4..bc619f4c 100644 --- a/versioned_docs/version-4.6/developers/applications/index.md +++ b/versioned_docs/version-4.6/developers/applications/index.md @@ -67,21 +67,21 @@ flowchart TD Rest --> Networking ``` -> As of Harper v4.6, a new, **experimental** component system has been introduced called **plugins**. Plugins are a **new iteration of the existing extension system**. They are simultaneously a simplification and an extensibility upgrade. Instead of defining multiple methods (`start` vs `startOnMainThread`, `handleFile` vs `setupFile`, `handleDirectory` vs `setupDirectory`), plugins only have to define a single `handleApplication` method. Plugins are **experimental**, and complete documentation is available on the [plugin API](../technical-details/reference/components/plugins) page. In time we plan to deprecate the concept of extensions in favor of plugins, but for now, both are supported. +> As of Harper v4.6, a new, **experimental** component system has been introduced called **plugins**. Plugins are a **new iteration of the existing extension system**. They are simultaneously a simplification and an extensibility upgrade. Instead of defining multiple methods (`start` vs `startOnMainThread`, `handleFile` vs `setupFile`, `handleDirectory` vs `setupDirectory`), plugins only have to define a single `handleApplication` method. Plugins are **experimental**, and complete documentation is available on the [plugin API](../reference/components/plugins) page. In time we plan to deprecate the concept of extensions in favor of plugins, but for now, both are supported. Beyond applications and extensions, components are further classified as built-in or custom. **Built-in** components are included with Harper by default and can be directly referenced by their name. The `graphqlSchema`, `rest`, and `jsResource` extensions used in the previous application example are all examples of built-in extensions. **Custom** components must use external references, generally npm or GitHub packages, and are often included as dependencies within the `package.json` of the component. > Harper maintains a number of custom components that are available on `npm` and `GitHub`, such as the [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs) extension or the [`@harperdb/status-check`](https://github.com/HarperDB/status-check) application. -Harper does not currently include any built-in applications, making "custom applications" a bit redundant. Generally, we just say "application". However, there is a multitude of both built-in and custom extensions, and so the documentation refers to them as such. A complete list of built-in extensions is available in the [Built-In Extensions](../technical-details/reference/components/built-in-extensions) documentation page, and the list of custom extensions and applications is available below. +Harper does not currently include any built-in applications, making "custom applications" a bit redundant. Generally, we just say "application". However, there is a multitude of both built-in and custom extensions, and so the documentation refers to them as such. A complete list of built-in extensions is available in the [Built-In Extensions](../reference/components/built-in-extensions) documentation page, and the list of custom extensions and applications is available below. This guide is going to walk you through building a basic Harper application using a set of built-in extensions. -> The Technical Details section of the documentation contains a [complete reference for all aspects of components](../technical-details/reference/components), applications, extensions, and more. +> The Reference -> Components section of the documentation contains a [complete reference for all aspects of components](../reference/components), applications, extensions, and more. ## Custom Functionality with JavaScript -[The getting started guide](../getting-started/first-harper-app) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../technical-details/reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +[The getting started guide](../getting-started/first-harper-app) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: @@ -211,11 +211,11 @@ Breed.sourcedFrom(BreedSource, { expiration: 3600 }); The [caching documentation](applications/caching) provides much more information on how to use Harper's powerful caching capabilities and set up data sources. -Harper provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../technical-details/reference/globals) and the [Resource interface](../technical-details/reference/resources/). +Harper provides a powerful JavaScript API with significant capabilities that go well beyond a "getting started" guide. See our documentation for more information on using the [`globals`](../reference/globals) and the [Resource interface](../reference/resources/). ## Configuring Applications/Components -For complete information of configuring applications, refer to the [Component Configuration](../technical-details/reference/components/configuration) reference page. +For complete information of configuring applications, refer to the [Component Configuration](../reference/components/configuration) reference page. ## Define Fastify Routes diff --git a/versioned_docs/version-4.6/getting-started/first-harper-app.md b/versioned_docs/version-4.6/getting-started/first-harper-app.md index 5390f98a..75cdfbab 100644 --- a/versioned_docs/version-4.6/getting-started/first-harper-app.md +++ b/versioned_docs/version-4.6/getting-started/first-harper-app.md @@ -163,7 +163,7 @@ http://localhost:9926/Dog/?breed=Husky&name=Balto&select(id,name,breed) Congratulations, you now have created a secure database application backend with a table, a well-defined structure, access controls, and a functional REST endpoint with query capabilities! See the [REST documentation for more information on HTTP access](../developers/rest) and see the [Schema reference](../developers/applications/defining-schemas) for more options for defining schemas. -> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../technical-details/reference/graphql). +> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../reference/graphql). ## Key Takeaway diff --git a/versioned_docs/version-4.6/getting-started/harper-concepts.md b/versioned_docs/version-4.6/getting-started/harper-concepts.md index c42f2fe9..0e88b0d1 100644 --- a/versioned_docs/version-4.6/getting-started/harper-concepts.md +++ b/versioned_docs/version-4.6/getting-started/harper-concepts.md @@ -8,13 +8,13 @@ As you begin your journey with Harper, there are a few concepts and definitions ## Components -Harper components are a core Harper concept defined as flexible JavaScript based extensions of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../technical-details/reference/globals) (such as Resource, databases, and tables). +Harper components are a core Harper concept defined as flexible JavaScript based extensions of the highly extensible core Harper platform. They are executed by Harper directly and have complete access to the Harper [Global APIs](../reference/globals) (such as Resource, databases, and tables). -A key aspect to components are their extensibility; components can be built on other components. For example, a [Harper Application](../developers/applications/) is a component that uses many other components. The [application template](https://github.com/HarperDB/application-template) demonstrates many of Harper's built-in components such as [rest](../technical-details/reference/components/built-in-extensions#rest) (for automatic REST endpoint generation), [graphqlSchema](../technical-details/reference/components/built-in-extensions#graphqlschema) (for table schema definitions), and many more. +A key aspect to components are their extensibility; components can be built on other components. For example, a [Harper Application](../developers/applications/) is a component that uses many other components. The [application template](https://github.com/HarperDB/application-template) demonstrates many of Harper's built-in components such as [rest](../reference/components/built-in-extensions#rest) (for automatic REST endpoint generation), [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) (for table schema definitions), and many more. ## Applications -Applications are a subset of components that cannot be used directly and must depend on other extensions. Examples include defining schemas (using [graphqlSchema](../technical-details/reference/components/built-in-extensions#graphqlschema) built-in extension), defining custom resources (using [jsResource](../technical-details/reference/components/built-in-extensions#jsresource) built-in extension), hosting static files (using [static](../technical-details/reference/components/built-in-extensions#static) built-in extension), enabling REST querying of resources (using [rest](../technical-details/reference/components/built-in-extensions#rest) built-in extension), and running [Next.js](https://github.com/HarperDB/nextjs), [Astro](https://github.com/HarperDB/astro), or [Apollo](https://github.com/HarperDB/apollo) applications through their respective extensions. +Applications are a subset of components that cannot be used directly and must depend on other extensions. Examples include defining schemas (using [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) built-in extension), defining custom resources (using [jsResource](../reference/components/built-in-extensions#jsresource) built-in extension), hosting static files (using [static](../reference/components/built-in-extensions#static) built-in extension), enabling REST querying of resources (using [rest](../reference/components/built-in-extensions#rest) built-in extension), and running [Next.js](https://github.com/HarperDB/nextjs), [Astro](https://github.com/HarperDB/astro), or [Apollo](https://github.com/HarperDB/apollo) applications through their respective extensions. ## Resources diff --git a/versioned_docs/version-4.6/getting-started/what-is-harper.md b/versioned_docs/version-4.6/getting-started/what-is-harper.md index ec7e31d3..60bc6a84 100644 --- a/versioned_docs/version-4.6/getting-started/what-is-harper.md +++ b/versioned_docs/version-4.6/getting-started/what-is-harper.md @@ -34,7 +34,7 @@ When you are ready for something a little more advanced, start [customizing your Finally, when it’s time to deploy, explore [replication](../developers/replication/) between nodes. -If you would like to jump into the most advanced capabilities, learn about [components](../technical-details/reference/components/). +If you would like to jump into the most advanced capabilities, learn about [components](../reference/components/). :::warning Need help? Please don’t hesitate to [reach out](https://www.harpersystems.dev/contact). diff --git a/versioned_docs/version-4.6/reference/_category_.json b/versioned_docs/version-4.6/reference/_category_.json new file mode 100644 index 00000000..d6302ac2 --- /dev/null +++ b/versioned_docs/version-4.6/reference/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Reference", + "position": 4, + "link": { + "type": "generated-index", + "title": "Reference Documentation", + "description": "Reference documentation and technical specifications", + "keywords": ["reference", "specifications"] + } +} diff --git a/versioned_docs/version-4.6/technical-details/reference/analytics.md b/versioned_docs/version-4.6/reference/analytics.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/analytics.md rename to versioned_docs/version-4.6/reference/analytics.md diff --git a/versioned_docs/version-4.6/technical-details/reference/architecture.md b/versioned_docs/version-4.6/reference/architecture.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/architecture.md rename to versioned_docs/version-4.6/reference/architecture.md diff --git a/versioned_docs/version-4.5/technical-details/reference/blob.md b/versioned_docs/version-4.6/reference/blob.md similarity index 97% rename from versioned_docs/version-4.5/technical-details/reference/blob.md rename to versioned_docs/version-4.6/reference/blob.md index a62ba2eb..9b6b1fb2 100644 --- a/versioned_docs/version-4.5/technical-details/reference/blob.md +++ b/versioned_docs/version-4.6/reference/blob.md @@ -103,4 +103,4 @@ if (blob.size === undefined) { ``` -See the [configuration](../../deployments/configuration) documentation for more information on configuring where blob are stored. +See the [configuration](../deployments/configuration) documentation for more information on configuring where blob are stored. diff --git a/docs/technical-details/reference/components/applications.md b/versioned_docs/version-4.6/reference/components/applications.md similarity index 93% rename from docs/technical-details/reference/components/applications.md rename to versioned_docs/version-4.6/reference/components/applications.md index 28cdcdcf..0bde610c 100644 --- a/docs/technical-details/reference/components/applications.md +++ b/versioned_docs/version-4.6/reference/components/applications.md @@ -12,7 +12,7 @@ Harper offers several approaches to managing applications that differ between lo Harper is designed to be simple to run locally. Generally, Harper should be installed locally on a machine using a global package manager install (i.e. `npm i -g harperdb`). -> Before continuing, ensure Harper is installed and the `harperdb` CLI is available. For more information, review the [installation guide](../../../deployments/install-harper/). +> Before continuing, ensure Harper is installed and the `harperdb` CLI is available. For more information, review the [installation guide](../../deployments/install-harper/). When developing an application locally there are a number of ways to run it on Harper. @@ -52,7 +52,7 @@ Alternatively, to mimic interfacing with a hosted Harper instance, use operation Similar to the previous section, if the main thread needs to be restarted, start and stop the Harper instance manually (with the application deployed). Upon Harper startup, the application will automatically be loaded and executed across all threads. -> Not all [component operations](../../../developers/operations-api/components) are available via CLI. When in doubt, switch to using the Operations API via network requests to the local Harper instance. +> Not all [component operations](../../developers/operations-api/components) are available via CLI. When in doubt, switch to using the Operations API via network requests to the local Harper instance. For example, to properly _deploy_ a `test-application` locally, the command would look like: @@ -69,7 +69,7 @@ Keep in mind that using a local file path for `package` will only work locally; ## Remote Management -Managing applications on a remote Harper instance is best accomplished through [component operations](../../../developers/operations-api/components), similar to using the `deploy` command locally. Before continuing, always backup critical Harper instances. Managing, deploying, and executing applications can directly impact a live system. +Managing applications on a remote Harper instance is best accomplished through [component operations](../../developers/operations-api/components), similar to using the `deploy` command locally. Before continuing, always backup critical Harper instances. Managing, deploying, and executing applications can directly impact a live system. Remote Harper instances work very similarly to local Harper instances. The primary application management operations still include `deploy_component`, `drop_component`, and `restart`. @@ -110,7 +110,7 @@ Furthermore, the `package` field can be set to any valid [npm dependency value]( - For applications deployed to npm, specify the package name: `package="@harperdb/status-check"` - For applications on GitHub, specify the URL: `package="https://github.com/HarperDB/status-check"`, or the shorthand `package=HarperDB/status-check` - Private repositories also work if the correct SSH keys are on the server: `package="git+ssh://git@github.com:HarperDB/secret-applications.git"` - - Reference the [SSH Key](../../../developers/operations-api/components#add-ssh-key) operations for more information on managing SSH keys on a remote instance + - Reference the [SSH Key](../../developers/operations-api/components#add-ssh-key) operations for more information on managing SSH keys on a remote instance - Even tarball URLs are supported: `package="https://example.com/application.tar.gz"` > When using git tags, we highly recommend that you use the semver directive to ensure consistent and reliable installation by npm. In addition to tags, you can also reference branches or commit numbers. diff --git a/versioned_docs/version-4.6/technical-details/reference/components/built-in-extensions.md b/versioned_docs/version-4.6/reference/components/built-in-extensions.md similarity index 91% rename from versioned_docs/version-4.6/technical-details/reference/components/built-in-extensions.md rename to versioned_docs/version-4.6/reference/components/built-in-extensions.md index 319183a5..49ec5fcb 100644 --- a/versioned_docs/version-4.6/technical-details/reference/components/built-in-extensions.md +++ b/versioned_docs/version-4.6/reference/components/built-in-extensions.md @@ -6,7 +6,7 @@ title: Built-In Extensions Harper provides extended features using built-in extensions. They do **not** need to be installed with a package manager, and simply must be specified in a config to run. These are used throughout many Harper docs, guides, and examples. Unlike custom extensions which have their own semantic versions, built-in extensions follow Harper's semantic version. -For more information read the [Components, Applications, and Extensions](../../../developers/applications/) documentation section. +For more information read the [Components, Applications, and Extensions](../../developers/applications/) documentation section. - [Built-In Extensions](#built-in-extensions) - [fastifyRoutes](#fastifyroutes) @@ -24,7 +24,7 @@ Load data from JSON or YAML files into Harper tables as part of component deploy This component is an [Extension](..#extensions) and can be configured with the `files` configuration option. -Complete documentation for this feature is available here: [Data Loader](../../../developers/applications/data-loader) +Complete documentation for this feature is available here: [Data Loader](../../developers/applications/data-loader) ```yaml dataLoader: @@ -37,7 +37,7 @@ Specify custom endpoints using [Fastify](https://fastify.dev/). This component is a [Resource Extension](./extensions#resource-extension) and can be configured with the [`files` and `urlPath`](./extensions#resource-extension-configuration) configuration options. -Complete documentation for this feature is available here: [Define Fastify Routes](../../../developers/applications/define-routes) +Complete documentation for this feature is available here: [Define Fastify Routes](../../developers/applications/define-routes) ```yaml fastifyRoutes: @@ -62,7 +62,7 @@ Specify schemas for Harper tables and resources via GraphQL schema syntax. This component is a [Resource Extension](./extensions#resource-extension) and can be configured with the [`files` and `urlPath`](./extensions#resource-extension-configuration) configuration options. -Complete documentation for this feature is available here: [Defining Schemas](../../../developers/applications/defining-schemas) +Complete documentation for this feature is available here: [Defining Schemas](../../developers/applications/defining-schemas) ```yaml graphqlSchema: @@ -73,7 +73,7 @@ graphqlSchema: Specify custom, JavaScript based Harper resources. -Refer to the Application [Custom Functionality with JavaScript](../../../developers/applications/#custom-functionality-with-javascript) guide, or [Resource Class](../resources/) reference documentation for more information on custom resources. +Refer to the Application [Custom Functionality with JavaScript](../../developers/applications/#custom-functionality-with-javascript) guide, or [Resource Class](../resources/) reference documentation for more information on custom resources. This component is a [Resource Extension](./extensions#resource-extension) and can be configured with the [`files` and `urlPath`](./extensions#resource-extension-configuration) configuration options. @@ -117,7 +117,7 @@ loadEnv: Enable automatic REST endpoint generation for exported resources with this component. -Complete documentation for this feature is available here: [REST](../../../developers/rest) +Complete documentation for this feature is available here: [REST](../../developers/rest) ```yaml rest: true @@ -145,7 +145,7 @@ Specify roles for Harper tables and resources. This component is a [Resource Extension](./extensions#resource-extension) and can be configured with the [`files` and `urlPath`](./extensions#resource-extension-configuration) configuration options. -Complete documentation for this feature is available here: [Defining Roles](../../../developers/applications/defining-roles) +Complete documentation for this feature is available here: [Defining Roles](../../developers/applications/defining-roles) ```yaml roles: diff --git a/versioned_docs/version-4.6/technical-details/reference/components/configuration.md b/versioned_docs/version-4.6/reference/components/configuration.md similarity index 97% rename from versioned_docs/version-4.6/technical-details/reference/components/configuration.md rename to versioned_docs/version-4.6/reference/components/configuration.md index 3e6108a0..2175a03d 100644 --- a/versioned_docs/version-4.6/technical-details/reference/components/configuration.md +++ b/versioned_docs/version-4.6/reference/components/configuration.md @@ -4,7 +4,7 @@ title: Component Configuration # Component Configuration -> For information on the distinction between the types of components (applications and extensions), refer to beginning of the [Applications](../../../developers/applications) documentation section. +> For information on the distinction between the types of components (applications and extensions), refer to beginning of the [Applications](../../developers/applications) documentation section. Harper components are configured with a `config.yaml` file located in the root of the component module directory. This file is how an components configures other components it depends on. Each entry in the file starts with a component name, and then configuration values are indented below it. diff --git a/versioned_docs/version-4.6/technical-details/reference/components/extensions.md b/versioned_docs/version-4.6/reference/components/extensions.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/components/extensions.md rename to versioned_docs/version-4.6/reference/components/extensions.md diff --git a/versioned_docs/version-4.6/technical-details/reference/components/index.md b/versioned_docs/version-4.6/reference/components/index.md similarity index 96% rename from versioned_docs/version-4.6/technical-details/reference/components/index.md rename to versioned_docs/version-4.6/reference/components/index.md index d2953776..30ce276d 100644 --- a/versioned_docs/version-4.6/technical-details/reference/components/index.md +++ b/versioned_docs/version-4.6/reference/components/index.md @@ -16,7 +16,7 @@ title: Components All together, the support for implementing a feature is the extension, and the actual implementation of the feature is the application. -For more information on the differences between applications and extensions, refer to the beginning of the [Applications](../../developers/applications/) guide documentation section. +For more information on the differences between applications and extensions, refer to the beginning of the [Applications](../developers/applications/) guide documentation section. This technical reference section has detailed information on various component systems: diff --git a/versioned_docs/version-4.6/technical-details/reference/components/plugins.md b/versioned_docs/version-4.6/reference/components/plugins.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/components/plugins.md rename to versioned_docs/version-4.6/reference/components/plugins.md diff --git a/docs/technical-details/reference/content-types.md b/versioned_docs/version-4.6/reference/content-types.md similarity index 98% rename from docs/technical-details/reference/content-types.md rename to versioned_docs/version-4.6/reference/content-types.md index 8d0feaf3..b7d223f4 100644 --- a/docs/technical-details/reference/content-types.md +++ b/versioned_docs/version-4.6/reference/content-types.md @@ -32,4 +32,4 @@ MessagePack is another efficient binary format like CBOR, with support for all H Comma-separated values is an easy to use and understand format that can be readily imported into spreadsheets or used for data processing. CSV lacks hierarchical structure for most data types, and shouldn't be used for frequent/production use, but when you need it, it is available. -In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../../developers/rest) for more information on how to do this. +In addition, with the REST interface, you can use file-style extensions to indicate an encoding like [https://host/path.csv](https://host/path.csv) to indicate CSV encoding. See the [REST documentation](../developers/rest) for more information on how to do this. diff --git a/versioned_docs/version-4.6/technical-details/reference/data-types.md b/versioned_docs/version-4.6/reference/data-types.md similarity index 93% rename from versioned_docs/version-4.6/technical-details/reference/data-types.md rename to versioned_docs/version-4.6/reference/data-types.md index 1591a6a5..8dd902e6 100644 --- a/versioned_docs/version-4.6/technical-details/reference/data-types.md +++ b/versioned_docs/version-4.6/reference/data-types.md @@ -4,7 +4,7 @@ title: Data Types # Data Types -Harper supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (Harper’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. Harper supports MessagePack and CBOR, which allows for all of Harper supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../../developers/rest)). Available data types include: +Harper supports a rich set of data types for use in records in databases. Various data types can be used from both direct JavaScript interfaces in Custom Functions and the HTTP operations APIs. Using JSON for communication naturally limits the data types to those available in JSON (Harper’s supports all of JSON data types), but JavaScript code and alternate data formats facilitate the use of additional data types. Harper supports MessagePack and CBOR, which allows for all of Harper supported data types. [Schema definitions can specify the expected types for fields, with GraphQL Schema Types](../developers/applications/defining-schemas), which are used for validation of incoming typed data (JSON, MessagePack), and is used for auto-conversion of untyped data (CSV, [query parameters](../developers/rest)). Available data types include: (Note that these labels are descriptive, they do not necessarily correspond to the GraphQL schema type names, but the schema type names are noted where possible) diff --git a/versioned_docs/version-4.6/technical-details/reference/dynamic-schema.md b/versioned_docs/version-4.6/reference/dynamic-schema.md similarity index 98% rename from versioned_docs/version-4.6/technical-details/reference/dynamic-schema.md rename to versioned_docs/version-4.6/reference/dynamic-schema.md index 2ca76839..161c3b13 100644 --- a/versioned_docs/version-4.6/technical-details/reference/dynamic-schema.md +++ b/versioned_docs/version-4.6/reference/dynamic-schema.md @@ -36,7 +36,7 @@ Harper automatically creates two audit attributes used on each record if the tab ### Dynamic Schema Example -To better understand the behavior let’s take a look at an example. This example utilizes [Harper API operations](../../developers/operations-api/databases-and-tables). +To better understand the behavior let’s take a look at an example. This example utilizes [Harper API operations](../developers/operations-api/databases-and-tables). **Create a Database** diff --git a/versioned_docs/version-4.6/technical-details/reference/globals.md b/versioned_docs/version-4.6/reference/globals.md similarity index 96% rename from versioned_docs/version-4.6/technical-details/reference/globals.md rename to versioned_docs/version-4.6/reference/globals.md index 2de4859f..c7616f01 100644 --- a/versioned_docs/version-4.6/technical-details/reference/globals.md +++ b/versioned_docs/version-4.6/reference/globals.md @@ -38,7 +38,7 @@ async function getRecord() { } ``` -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. +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. ## `databases` @@ -59,7 +59,7 @@ This returns the user object with permissions/authorization information based on ## `logger` -This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../../administration/logging/standard-logging) for more information. +This provides methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `notify` for logging. See the [logging documentation](../administration/logging/standard-logging) for more information. ## `server` @@ -256,7 +256,7 @@ Properties: ### `server.config` -This provides access to the Harper configuration object. This comes from the [harperdb-config.yaml](../../deployments/configuration) (parsed into object form). +This provides access to the Harper configuration object. This comes from the [harperdb-config.yaml](../deployments/configuration) (parsed into object form). ### `server.recordAnalytics(value, metric, path?, method?, type?)` @@ -304,7 +304,7 @@ server.resources.getMatch('/NewResource/some-id', 'my-protocol'); ### `server.operation(operation: Object, context?: Object, authorize?: boolean)` -Execute an operation from the [Operations API](../../developers/operations-api) +Execute an operation from the [Operations API](../developers/operations-api) Parameters: @@ -312,7 +312,7 @@ Parameters: - `context` - `Object` - `{ username: string}` - _optional_ - The specified user - `authorize` - `boolean` - _optional_ - Indicate the operation should authorize the user or not. Defaults to `false` -Returns a `Promise` with the operation's response as per the [Operations API documentation](../../developers/operations-api). +Returns a `Promise` with the operation's response as per the [Operations API documentation](../developers/operations-api). ### `server.nodes` diff --git a/versioned_docs/version-4.6/technical-details/reference/graphql.md b/versioned_docs/version-4.6/reference/graphql.md similarity index 98% rename from versioned_docs/version-4.6/technical-details/reference/graphql.md rename to versioned_docs/version-4.6/reference/graphql.md index 1626e97c..cc43eec9 100644 --- a/versioned_docs/version-4.6/technical-details/reference/graphql.md +++ b/versioned_docs/version-4.6/reference/graphql.md @@ -4,7 +4,7 @@ title: GraphQL Querying # GraphQL Querying -Harper supports GraphQL in a variety of ways. It can be used for [defining schemas](../../developers/applications/defining-schemas), and for querying [Resources](./resources/). +Harper supports GraphQL in a variety of ways. It can be used for [defining schemas](../developers/applications/defining-schemas), and for querying [Resources](./resources/). Get started by setting `graphql: true` in `config.yaml`. diff --git a/versioned_docs/version-4.6/technical-details/reference/headers.md b/versioned_docs/version-4.6/reference/headers.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/headers.md rename to versioned_docs/version-4.6/reference/headers.md diff --git a/versioned_docs/version-4.6/technical-details/reference/index.md b/versioned_docs/version-4.6/reference/index.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/index.md rename to versioned_docs/version-4.6/reference/index.md diff --git a/versioned_docs/version-4.6/technical-details/reference/limits.md b/versioned_docs/version-4.6/reference/limits.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/limits.md rename to versioned_docs/version-4.6/reference/limits.md diff --git a/versioned_docs/version-4.6/technical-details/reference/resources/index.md b/versioned_docs/version-4.6/reference/resources/index.md similarity index 98% rename from versioned_docs/version-4.6/technical-details/reference/resources/index.md rename to versioned_docs/version-4.6/reference/resources/index.md index 7a833105..603cca11 100644 --- a/versioned_docs/version-4.6/technical-details/reference/resources/index.md +++ b/versioned_docs/version-4.6/reference/resources/index.md @@ -272,7 +272,7 @@ When a resource is accessed as a data source: ### `operation(operationObject: Object, authorize?: boolean): Promise` -This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). +This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). ### `allowStaleWhileRevalidate(entry: { version: number, localTime: number, expiresAt: number, value: object }, id): boolean` @@ -373,7 +373,7 @@ type MyTable @table { } ``` -See the [schema documentation](../../developers/applications/defining-schemas) for more information on computed attributes. +See the [schema documentation](../developers/applications/defining-schemas) for more information on computed attributes. ### `primaryKey` @@ -490,7 +490,7 @@ Table.search({ **Chained Attributes/Properties** -Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../developers/applications/defining-schemas), see the [REST documentation](../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: +Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../developers/applications/defining-schemas) (in addition to the [schema documentation](../developers/applications/defining-schemas), see the [REST documentation](../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: ```javascript Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] }); diff --git a/versioned_docs/version-4.6/technical-details/reference/resources/instance-binding.md b/versioned_docs/version-4.6/reference/resources/instance-binding.md similarity index 97% rename from versioned_docs/version-4.6/technical-details/reference/resources/instance-binding.md rename to versioned_docs/version-4.6/reference/resources/instance-binding.md index 4d07190f..45bbcd47 100644 --- a/versioned_docs/version-4.6/technical-details/reference/resources/instance-binding.md +++ b/versioned_docs/version-4.6/reference/resources/instance-binding.md @@ -253,7 +253,7 @@ When a resource is accessed as a data source: ### `operation(operationObject: Object, authorize?: boolean): Promise` -This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../../../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). +This method is available on tables and will execute a Harper operation, using the current table as the target of the operation (the `table` and `database` do not need to be specified). See the [operations API](../../developers/operations-api/) for available operations that can be performed. You can set the second argument to `true` if you want the current user to be checked for authorization for the operation (if `true`, will throw an error if they are not authorized). ### `allowStaleWhileRevalidate(entry: { version: number, localTime: number, expiresAt: number, value: object }, id): boolean` @@ -360,7 +360,7 @@ type MyTable @table { } ``` -See the [schema documentation](../../../developers/applications/defining-schemas) for more information on computed attributes. +See the [schema documentation](../../developers/applications/defining-schemas) for more information on computed attributes. ### `primaryKey` @@ -477,7 +477,7 @@ Table.search({ **Chained Attributes/Properties** -Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../../developers/applications/defining-schemas), see the [REST documentation](../../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: +Chained attribute/property references can be used to search on properties within related records that are referenced by [relationship properties](../../developers/applications/defining-schemas) (in addition to the [schema documentation](../../developers/applications/defining-schemas), see the [REST documentation](../../developers/rest) for more of overview of relationships and querying). Chained property references are specified with an array, with each entry in the array being a property name for successive property references. For example, if a relationship property called `brand` has been defined that references a `Brand` table, we could search products by brand name: ```javascript Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] }); diff --git a/versioned_docs/version-4.6/technical-details/reference/resources/migration.md b/versioned_docs/version-4.6/reference/resources/migration.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/resources/migration.md rename to versioned_docs/version-4.6/reference/resources/migration.md diff --git a/versioned_docs/version-4.6/technical-details/reference/storage-algorithm.md b/versioned_docs/version-4.6/reference/storage-algorithm.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/storage-algorithm.md rename to versioned_docs/version-4.6/reference/storage-algorithm.md diff --git a/versioned_docs/version-4.6/technical-details/reference/transactions.md b/versioned_docs/version-4.6/reference/transactions.md similarity index 100% rename from versioned_docs/version-4.6/technical-details/reference/transactions.md rename to versioned_docs/version-4.6/reference/transactions.md diff --git a/versioned_docs/version-4.6/technical-details/_category_.json b/versioned_docs/version-4.6/technical-details/_category_.json deleted file mode 100644 index b965ef06..00000000 --- a/versioned_docs/version-4.6/technical-details/_category_.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "label": "Technical Details", - "position": 4, - "link": { - "type": "generated-index", - "title": "Technical Details Documentation", - "description": "Reference documentation and technical specifications", - "keywords": ["technical-details"] - } -} diff --git a/versioned_sidebars/version-4.2-sidebars.json b/versioned_sidebars/version-4.2-sidebars.json index 33d81913..f4ff0475 100644 --- a/versioned_sidebars/version-4.2-sidebars.json +++ b/versioned_sidebars/version-4.2-sidebars.json @@ -38,11 +38,11 @@ }, { "type": "category", - "label": "Technical Details", + "label": "Reference", "items": [ { "type": "autogenerated", - "dirName": "technical-details" + "dirName": "reference" } ] } diff --git a/versioned_sidebars/version-4.3-sidebars.json b/versioned_sidebars/version-4.3-sidebars.json index 33d81913..f4ff0475 100644 --- a/versioned_sidebars/version-4.3-sidebars.json +++ b/versioned_sidebars/version-4.3-sidebars.json @@ -38,11 +38,11 @@ }, { "type": "category", - "label": "Technical Details", + "label": "Reference", "items": [ { "type": "autogenerated", - "dirName": "technical-details" + "dirName": "reference" } ] } diff --git a/versioned_sidebars/version-4.4-sidebars.json b/versioned_sidebars/version-4.4-sidebars.json index 33d81913..f4ff0475 100644 --- a/versioned_sidebars/version-4.4-sidebars.json +++ b/versioned_sidebars/version-4.4-sidebars.json @@ -38,11 +38,11 @@ }, { "type": "category", - "label": "Technical Details", + "label": "Reference", "items": [ { "type": "autogenerated", - "dirName": "technical-details" + "dirName": "reference" } ] } diff --git a/versioned_sidebars/version-4.5-sidebars.json b/versioned_sidebars/version-4.5-sidebars.json index 9fa0770b..11a21717 100644 --- a/versioned_sidebars/version-4.5-sidebars.json +++ b/versioned_sidebars/version-4.5-sidebars.json @@ -51,11 +51,11 @@ }, { "type": "category", - "label": "Technical Details", + "label": "Reference", "items": [ { "type": "autogenerated", - "dirName": "technical-details" + "dirName": "reference" } ] } diff --git a/versioned_sidebars/version-4.6-sidebars.json b/versioned_sidebars/version-4.6-sidebars.json index 9fa0770b..11a21717 100644 --- a/versioned_sidebars/version-4.6-sidebars.json +++ b/versioned_sidebars/version-4.6-sidebars.json @@ -51,11 +51,11 @@ }, { "type": "category", - "label": "Technical Details", + "label": "Reference", "items": [ { "type": "autogenerated", - "dirName": "technical-details" + "dirName": "reference" } ] }