diff --git a/docfx.json b/docfx.json index b7f907b..b9ce5a8 100644 --- a/docfx.json +++ b/docfx.json @@ -4,7 +4,9 @@ "content": [ { "files": [ - "**/*.{md,yml}" + "index.md", + "toc.yml", + "docs/**/*.{md,yml}" ], "exclude": [ "_site/**" diff --git a/docs/basic-usage.md b/docs/basic-usage.md new file mode 100644 index 0000000..f88edd4 --- /dev/null +++ b/docs/basic-usage.md @@ -0,0 +1,7 @@ +# Basic Usage + +Documentation is in active development; and this page is next. Until it is more complete, the flow is very similar to [BitBadger.Documents](https://bitbadger.solutions/open-source/relational-documents/dotnet/basic-usage.html), the .NET implementation of a similar library. This library also supports `Json` in place of `Find` to return raw JSON, and `Json.write*` to write that JSON to a `PrintWriter`, bypassing the entire deserialize-from-the-database, serialize-to-the-output-body process.) + +## Examples + +Each library has an exhaustive suite of integration tests; reviewing those may also provide insight into the patterns used for effective document storage and retrieval. diff --git a/docs/getting-started.md b/docs/getting-started.md index 9bf7eb8..23c7d0a 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -78,27 +78,47 @@ Any of the [KotlinX Json][kx-json] properties can be set on the `options` proper > [!NOTE] > If you want to customize the document's `id` field, this needs be done before tables are created. -The final step to being able to store and retrieve documents is to define one or more tables for them. +The final step to being able to store and retrieve documents is to define one or more tables for them. The `Definition` class (in the `.java`, `.scala`, or `.kotlinx` packages) provides an `ensureTable` method that creates both a table and its ID index if that table does not already exist. (`ensureTable` is also a `Connection` extension method.) -// TODO: stopped here +To create a document table named `hotel` in Java... -## Previous Instructions +```java +// Function that creates its own connection +Definition.ensureTable("hotel"); +// ...or, on a connection variable named "conn" +conn.ensureTable("hotel"); +``` -The exceedingly quick version: +> [!NOTE] +> Most operations could throw `DocumentException`, which is a checked exception. Java consumers must catch or declare it; for other languages, "must" becomes "should consider". -- Add the desired module/package to your dependencies -- Implement an instance of the `DocumentSerializer` interface and assign it to the `DocumentConfig.serializer` property (for all but kotlinx) -- Set a PostgreSQL or SQLite JDBC connection string for the `Configuration.connectionString` property +The repeatable nature of this call means that your application can run through a set of `ensureTable` calls at startup. -At this point, `Connection.dbConn()` will provide a connection which can be used either for function calls or extension method calls. You will also be able to call functions without providing a connection, and the library will create one for that command. (Database pooling will help reduce connection overhead when using this technique.) +### Indexing Documents -From there, `Definition.ensureTable(name)` will create a table, and you are ready to start manipulating documents! +Both PostgreSQL and SQLite support indexing individual fields in the document, just as they can index columns in a relational table. `Definition` provides the `ensureFieldIndex` method to establish these indexes. These functions take a table name, an index name, and a collection of field names from the document which should be indexed. -(Documentation is in active development; until it is more complete, the flow is very similar to [BitBadger.Documents](https://bitbadger.solutions/open-source/relational-documents/dotnet/basic-usage.html), the .NET implementation of a similar library. This library also supports `Json` in place of `Find` to return raw JSON, and `Json.write*` to write that JSON to a `PrintWriter`, bypassing the entire deserialize-from-the-database, serialize-to-the-output-body process.) +For example, imagine we had a `user` document, but we allow users to sign in via their e-mail address. In Java, this may look something like... -## Examples +```java +// Create an index named idx_user_email on the user table +Definition.ensureFieldIndex("user", "email", List.of("email")); +``` -Each library has an exhaustive suite of integration tests; reviewing those may also provide insight into the patterns used for effective document storage and retrieval. +Multiple-field indexes are also possible. + +For PostgreSQL, they provide a GIN index which can index the entire document. This index can be a full document index, which can be used for both containment queries or JSON Path matching queries, or one that is optimized for JSON Path operations. This library has a `DocumentIndex` enum with values `Full` and `Optimized` to specify which type of index is required. `ensureDocumentIndex` creates the index. + +```java +// This index will be named idx_user_doc and is suitable for any operation +Definition.ensureDocumentIndex("user", DocumentIndex.Full); +``` + +Indexes are not as important an up-front decision as some other aspects; nothing prevents a developer from adding an index when they realize they may need one. + +--- + +We have access to a data store, we know how to create documents, and we have a place to store them. Now, it's time to use all that! [env]: https://docs.oracle.com/javase/tutorial/essential/environment/env.html "Environment Variables • The Java Tutorials" diff --git a/docs/toc.yml b/docs/toc.yml index 6c61598..3ce17bc 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,2 +1,4 @@ - name: Getting Started - href: getting-started.md \ No newline at end of file + href: getting-started.md +- name: Basic Usage + href: basic-usage.md diff --git a/index.md b/index.md index b408d27..336beb7 100644 --- a/index.md +++ b/index.md @@ -42,7 +42,7 @@ This module utilizes [`kotlix.serialization`][kotlinx] for its serialization and ## Talk about Them -Bit Badger Solutions' Git is not set up for account registration _(yet! -- Homer Simpson)_. However, the author can be reached as `@Bit_Badger` on Twitter, `daniel@fedi.summershome.org` on the Fediverse, or via e-mail as `daniel` at the parent domain to this site's domain. This project is open to the public, so you will be able to track the progress of any issues you may report. +Bit Badger Solutions Git is not set up for account registration _(yet! -- Homer Simpson)_. However, the author can be reached as `@Bit_Badger` on Twitter, `daniel@fedi.summershome.org` on the Fediverse, or via e-mail as `daniel` at the parent domain to this site's domain. This project is open to the public, so you will be able to track the progress of any issues you may report. [core-badge]: https://img.shields.io/maven-central/v/solutions.bitbadger.documents/core