Add examples

Author: hoijnet

src/app/docs/cookbook-woql-type-of-datatype/page.md

@@ -0,0 +1,141 @@
+---
+title: "WOQL Cookbook: Finding and matching datatypes"
+nextjs:
+  metadata:
+    title: "WOQL Cookbook: Finding and matching datatypes"
+    description: Examples of WOQL query patterns with datatypes using the WOQL datalog type_of() in three different ways
+    keywords: woql, query, datalog, cookbook, declarative logic
+    openGraph:
+      images: https://assets.terminusdb.com/docs/technical-documentation-terminuscms-og.png
+    alternates:
+      canonical: https://terminusdb.org/docs/cookbook-woql-query-patterns/
+media: []
+---
+
+This page is intended to show how to accomplish goals with WOQL. Before really "getting" WOQL, it feels counter-intuitive as solutions are generated using patterns.
+
+Logicians and people hanving used prolog, datalog and similar declarative languages will find it easier to understand the core concepts of unification and generator patterns and we hope the examples on this page will help show common solutions.
+
+## How the examples on this page work
+
+Most of the work in TerminusDB happens with data that is stored in the instance graph. WOQL is not limited to processing stored graph information, it is also possible to process supplied CSV files and build patterns using the `member()` predicate.
+
+The examples on the first section of the page are kept as simple as possible, to enable running them without schema or instance data. The second section will require a schema and instance data with some instructions on how to set it up.
+
+You are expected to have instance data to query and a basic undertanding of querying triples of the graph and processing documents with knowledge of datatypes, sets, lists, arrays etc.
+
+## Variables
+
+Variable unification is core to the WOQL engine. Read up on [unification](/docs/unification-of-variables-in-datalog/) if you are unsure, and play with the examples on this page to learn.
+
+## Understanding value types
+
+All values that are processed in TerminusDB are of a certain type. Sometimes it's important to either match a type, understand what datatype a value has, or to match elements in a variable to a datatype.
+
+Thanks to pattern matching this can be done with the very same predicate, used in multiple ways.
+
+### Code: Which type a value has
+
+The `type_of` predicate can be used to bind a variable to the type of a value, `v:datatype` in this example. This is useful when you want to match values with specific types, such as specific classes of integers, or match all kinds of decimal numbers, floats and doubles.
+
+```woql
+and(
+  member("v:list", [literal("MyString", "xsd:string"), literal(1, "xsd:integer")]),
+  type_of("v:list", "v:datatype")
+)
+```
+
+The above yields:
+
+{% table %}
+
+- list
+- datatype
+
+---
+
+- MyString
+- xsd:string
+
+---
+
+- 1
+- xsd:integer
+
+{% /table %}
+
+### Code: Which value is a string?
+
+Here we use `type_of()` in a different way, where we instead bind the type parameter to a specific type, `xsd:string`, to constrain the allowed values in `v:list` for the solutions to return.
+
+```woql
+and(
+  member("v:list", [
+    literal("MyString1", "xsd:string"),
+    literal(1, "xsd:integer"),
+    literal("MyString2", "xsd:string")
+  ]),
+  type_of("v:list", "xsd:string")
+)
+```
+
+The above yields:
+
+{% table %}
+
+- list
+
+---
+
+- MyString1
+
+---
+
+- MyString2
+
+{% /table %}
+
+### Code: Is a specific value a string?
+
+In the last example, which is a bit contrived, we check if the literal string is a string, and bind a variable to a value if the comparison is true.
+
+What is important in this example is that all statements of the `and()` predicate must resolve to true for it to be a solution. Thus, we know that there must be equality for a solution to be returned.
+
+To make this a bit more interesting, we use optionality to offer two variables that are both optional so that only one solution is returned, where one comparison is true, and the other isn't.
+
+In order to satisfy the `and()` predicate, the solution result of the literal check needs to be inverted using the `not()` operator, and then the `eq()` operator sets the variable `v:is_integer` to be `false` as the result of the comparison is not true.
+
+```woql
+and(
+  opt().and(
+    type_of(literal("", "xsd:string"), "xsd:string"),
+    eq("v:is_string", true)
+  ),
+  opt().and(
+    not().type_of(literal("", "xsd:string"), "xsd:integer"),
+    eq("v:is_integer", false)
+  )
+)
+```
+
+The above yields:
+
+{% table %}
+
+- is_string
+- is_integer
+
+---
+
+- true
+- false
+
+{% /table %}
+
+## Conclusion
+
+WOQL predicates can be used in many ways. Through clever use of them, problems that are hard to solve in other ways, often get elegant solutions using WOQL, thanks to the powerful pattern matching capabilities of WOQL and the flexible use of variables. 
+
+Traditional database query languages like SQL are limited to the data and the columns that are available, which makes it hard to write solutions with declarative logic.
+
+The flexibility to use the logical predicates in multiple ways makes it practical to write solutions using declarative logic.

src/app/docs/how-to-query/page.md

@@ -0,0 +1,132 @@
+---
+title: "WOQL Cookbook: Pattern generation"
+nextjs:
+  metadata:
+    title: "WOQL Cookbook: Pattern generation"
+    description: Examples of WOQL pattern generation using the WOQL datalog substr() predicate that generates all possible solutions in a novel way
+    keywords: woql, query, datalog, cookbook, declarative logic
+    openGraph:
+      images: https://assets.terminusdb.com/docs/technical-documentation-terminuscms-og.png
+    alternates:
+      canonical: https://terminusdb.org/docs/pattern-generation-cookbook/
+media: []
+---
+
+When faced with combinatorial problems, it is hard to know where to start. Using a logic engine to exhaust possible solutions is a novel way to approach such problems, and leverages an engine to do the hard work for us.
+
+In this example we will explore specifically how the `substr()` predicate can be used to generate all possible substrings of a string using rules.
+
+## Example of pattern generation
+
+A simple pattern that shows the pattern generation is the `substr()` predicate:
+
+```woql
+substr(string, before, length, after, subString)
+```
+
+### Introducing pattern generation with two simple examples
+
+Notice that there is only one solution for example 1 below, and two solutions for example 2, as the possible solutions for the open ended variables will be generated automatically by the engine.
+
+#### Code: Example 1 of substr
+
+```javascript
+substr("string", 2, 2, "v:after", "ri")
+```
+
+This returns `2`, as it has 2 characters before the substring `ri`, and we use 2 characters of the substring `ri`.
+
+#### Code: Example 2 of substr
+
+```javascript
+substr("string", "v:before", 5, "v:after", "v:subString")
+```
+
+Now, this query will return two solutions:
+* First solution has `before=0` and `after=1`, and `subString="strin"`
+* Second solution has `before=1` and `after=0`, and `subString="tring"`
+
+
+
+### Combining the pattern generation with rules
+
+Let's increase the complexity of the solution by adding rules for the allowed solutions and make the string a bit more complex to match against.
+
+Note that values in TerminusDB default to being treated as IRIs, unless specifically typed as specific literals, or that the context makes a specific choice for how to interpret a parameter, such as when supplying a pattern to match to `substr()`.
+
+What we are doing here is matching a string that has a pattern of 8 groups of 4 digits separated by hyphens. We want to get one solution per number as an integer, and know the string positions where that number was found.
+
+By matching on `-` we can filter out substrings that do not include a hyphen.
+
+#### Code: Example 3 of substr
+
+```woql
+select().and(
+  // Let variable string have the string of numbers
+  eq("v:string", literal("0000-0001-0002-0003-0004-0005-0006-0007", "xsd:string")),
+
+  // Get every possible substring of 4 characters
+  substr("v:string", "v:start", 4, "v:end", "v:str"),
+  // Filter out substrings with a hyphen and convert to integer
+  and(
+      not().substr("v:str", "v:n_1", "v:n_2", "v:n_3", "-"),
+      typecast("v:str", "xsd:integer", "v:number")
+  )
+)
+```
+
+Here is the result of the logic.
+
+{% table %}
+
+- 0
+- 0
+- 0000
+
+---
+
+- 1
+- 5
+- 0001
+
+---
+
+- 2
+- 10
+- 0002
+
+---
+
+- 3
+- 15
+- 0003
+
+---
+
+- 4
+- 20
+- 0004
+
+---
+
+- 5
+- 25
+- 0005
+
+---
+
+- 6
+- 30
+- 0006
+
+---
+
+- 7
+- 35
+- 0007
+
+{% /table %}
+
+## Conclusion
+
+The examples shows how to use pattern generation to match against string patterns and extract values from it. Every possible solution is generated automatically by the engine to match against.

src/app/docs/pattern-generation-cookbook/page.md

@@ -0,0 +1,58 @@
+---
+title: TerminusDB Query Cookbook
+nextjs:
+  metadata:
+    title: TerminusDB Query Cookbook
+    description: Guides showing how to query using GraphQL, WOQL and in other ways
+    keywords: TerminusDB, TerminusDB Cloud, TerminusDB Open Source, TerminusDB Documentation, TerminusDB Query, TerminusDB Query Cookbook
+    openGraph:
+      images: https://assets.terminusdb.com/docs/technical-documentation-terminuscms-og.png
+    alternates:
+      canonical: https://terminusdb.org/docs/how-to-query/
+media: []
+---
+## Getting Started
+
+TerminusDB Query Cookbook is a collection of guides showing how to query using GraphQL, WOQL and in other ways. TerminusDB is a graph database and document store that is great for data integration, knowledge management, knowledge engineering, content management, and data analytics.
+
+* [Getting Started with WOQL](/docs/woql-getting-started)
+
+In this guide, we introduce the basic concepts of WOQL and show how to use it to query a TerminusDB database.
+
+## Datatypes
+
+WOQL is powerful enough to support a wide range of datatypes. In this guide, we show how to use WOQL to query TerminusDB using different datatypes.
+
+* [Cookbook: Datatypes](/docs/cookbook-woql-type-of-datatype)
+
+This guide covers how to match datatypes, understand the datatype of a value and check that a value is of a datatype.
+
+## Git-for-data, query across graphs
+
+TerminusDB includes a Git-for-data feature that also allows you to query across knowledge graphs.
+
+* [Cookbook: Many Graphs](/docs/datalog-queries-between-data-products/)
+
+This guide shows how to use WOQL to query a TerminusDB data product that has many graphs, or between completely separate data products.
+
+## Pattern Generation
+
+In this guide, we show how to use WOQL to query a TerminusDB database with pattern generation.
+
+* [Cookbook: Pattern Generation](/docs/pattern-generation-cookbook/)
+
+
+## Querying TerminusDB Databases with GraphQL
+
+In this guide, we show how to use GraphQL to query a TerminusDB database within and across documents that are stored as graph objects.
+
+It covers how to use GraphQL to query for data in a TerminusDB database, including how to use the `query` keyword and how to use the `mutation` keyword.
+
+* [GraphQL Query](/docs/how-to-query-with-graphql//)
+
+### Querying TerminusDB Databases with WOQL
+
+
+In this guide, we show how to query a TerminusDB database using WOQL. It covers how to use WOQL to query for graph data and triples stored in a TerminusDB database.
+
+* [WOQL Query](/docs/how-to-query-with-woql/)