From aaedd48a6515f52171da178f8ac49ede61b6c3bf Mon Sep 17 00:00:00 2001 From: Neelterminusdb Date: Wed, 3 May 2023 08:27:57 +0000 Subject: [PATCH] Update from https://github.com/terminusdb/terminusdb-client-js/commit/f2f756e8a0760582573e635574425f891eacc4e3 --- .../accesscontrol.md | 18 + .../javascript-client-reference/typedef.md | 26 +- .../javascript-client-reference/woql.md | 1647 ++++++++--------- .../javascript-client-reference/woqlclient.md | 1277 +++++++------ 4 files changed, 1407 insertions(+), 1561 deletions(-) diff --git a/guides/reference-guides/javascript-client-reference/accesscontrol.md b/guides/reference-guides/javascript-client-reference/accesscontrol.md index 3b642a28..5c13d067 100644 --- a/guides/reference-guides/javascript-client-reference/accesscontrol.md +++ b/guides/reference-guides/javascript-client-reference/accesscontrol.md @@ -707,3 +707,21 @@ accessControl.deleteAccessRequest("djjdshhsuuwewueueuiHYHYYW.......").then(resul console.log(result) }) ``` + +## getUserInfo +##### accessControl.getUserInfo([orgName]) ⇒ Promise +-- TerminusX API -- +Get the userinfo teams ownership and subscription + +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. + +| Param | Type | Description | +| --- | --- | --- | +| [orgName] | string | The organization name. | + +**Example** +```javascript +accessControl.getUserInfo().then(result=>{ + console.log(result) +}) +``` diff --git a/guides/reference-guides/javascript-client-reference/typedef.md b/guides/reference-guides/javascript-client-reference/typedef.md index f9e07508..798b520f 100644 --- a/guides/reference-guides/javascript-client-reference/typedef.md +++ b/guides/reference-guides/javascript-client-reference/typedef.md @@ -47,6 +47,7 @@ the PUT document interface query parameters | Name | Type | Description | | --- | --- | --- | | [raw_json] | boolean | default is false, If true, the input documents are treated as raw JSON, inserted as type sys:JSONDocument and are not subject to schema restrictions. | +| [create] | boolean | If true, the function will create a new document if it doesn't exist. | | [graph_type] | GraphType | default is instance, instance|schema Used to switch between getting documents from the instance or the schema graph. | @@ -60,7 +61,7 @@ the DELETE document interface query parameters | --- | --- | --- | | [graph_type] | GraphType | default is instance, instance|schema Used to switch between getting documents from the instance or the schema graph. | | id | string \| array | a single id or a list of ids to delete. | -| [nuke] | booleam | default is false, If true, delete everything at this resource location (dangerous!). | +| [nuke] | boolean | default is false, If true, delete everything at this resource location (dangerous!). | ## GraphRef @@ -199,3 +200,26 @@ the manage capability command type ##### RolesActions: ` Array.` [ACTIONS.CREATE_DATABASE | ACTIONS.DELETE_DATABASE] + +## DocHistoryParams +##### DocHistoryParams: ` Object` +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| [start] | number | Index to start from, 0 is the default | +| [count] | number | Amount of commits to show, 10 is the default | +| [updated] | boolean | Last updated time (excludes history) false is the default | +| [created] | boolean | Created date of object (excludes history) false is the default | + + +## DiffObject +##### DiffObject: ` Object` +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| [Object] | keep | Index to start from, 0 is the default | +| [number] | start | Amount of commits to show, 10 is the default | +| [number] | count | Last updated time (excludes history) false is the default | + diff --git a/guides/reference-guides/javascript-client-reference/woql.md b/guides/reference-guides/javascript-client-reference/woql.md index 2d79a64f..05d28a52 100644 --- a/guides/reference-guides/javascript-client-reference/woql.md +++ b/guides/reference-guides/javascript-client-reference/woql.md @@ -1,52 +1,49 @@ -# WOQL +# WOQL ## WOQL - -**License**: Apache Version 2 +**License**: Apache Version 2 ## new WOQL() +The WOQL object is a wrapper around the WOQLQuery object +Syntactic sugar to allow writing WOQL.triple()... instead of new WOQLQuery().triple() +Every function matches one of the public api functions of the woql query object -The WOQL object is a wrapper around the WOQLQuery object Syntactic sugar to allow writing WOQL.triple()... instead of new WOQLQuery().triple() Every function matches one of the public api functions of the woql query object ## using - -**WOQL.using(refPath, \[subquery]) ⇒ `WOQLQuery`** - +##### WOQL.using(refPath, [subquery]) ⇒ WOQLQuery Query running against any specific commit Id -| Param | Type | Description | -| ----------- | ----------- | ------------------------------------------ | -| refPath | `string` | path to specific reference Id or commit Id | -| \[subquery] | `WOQLQuery` | subquery for the specific commit point | -**Example** +| Param | Type | Description | +| --- | --- | --- | +| refPath | string | path to specific reference Id or commit Id | +| [subquery] | WOQLQuery | subquery for the specific commit point | +**Example** ```javascript let [a, b, c] = vars("a", "b", "c") WOQL.using("userName/dbName/local/commit|branch/commitID").triple(a, b, c) ``` ## comment - -**WOQL.comment(comment, \[subquery]) ⇒ `WOQLQuery`** - +##### WOQL.comment(comment, [subquery]) ⇒ WOQLQuery Adds a text comment to a query - can also be used to wrap any part of a query to turn it off -| Param | Type | Description | -| ----------- | ----------- | ----------------------------- | -| comment | `string` | text comment | -| \[subquery] | `WOQLQuery` | query that is "commented out" | -## select +| Param | Type | Description | +| --- | --- | --- | +| comment | string | text comment | +| [subquery] | WOQLQuery | query that is "commented out" | -**WOQL.select(varNames) ⇒ `WOQLQuery`** -| Param | Type | Description | -| -------- | ----------------- | --------------------------------- | -| varNames | `string` \| `Var` | only these variables are returned | +## select +##### WOQL.select(varNames) ⇒ WOQLQuery -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varNames | string \| Var | only these variables are returned | +**Example** ```javascript let [a, b, c] = vars("a", "b", "c") WOQL.select(a, triple(a, b, c)) @@ -54,29 +51,26 @@ Filters the query so that only the variables included in [V1...Vn] are returned ``` ## distinct - -**WOQL.distinct(varNames) ⇒ `WOQLQuery`** - +##### WOQL.distinct(varNames) ⇒ WOQLQuery Filter the query to return only results that are distinct in the given variables -| Param | Type | Description | -| -------- | ----------------- | ------------------------------------------------------ | -| varNames | `string` \| `Var` | these variables are guaranteed to be unique as a tuple | -## and +| Param | Type | Description | +| --- | --- | --- | +| varNames | string \| Var | these variables are guaranteed to be unique as a tuple | -**WOQL.and(...subqueries) ⇒ `WOQLQuery`** +## and +##### WOQL.and(...subqueries) ⇒ WOQLQuery Logical conjunction of the contained queries - all queries must match or the entire clause fails -**Returns**: `WOQLQuery` - - A WOQLQuery object containing the conjunction of queries - -| Param | Type | Description | -| ------------- | ----------- | -------------------------------------------------------------- | -| ...subqueries | `WOQLQuery` | A list of one or more woql queries to execute as a conjunction | +**Returns**: WOQLQuery - - A WOQLQuery object containing the conjunction of queries -**Example** +| Param | Type | Description | +| --- | --- | --- | +| ...subqueries | WOQLQuery | A list of one or more woql queries to execute as a conjunction | +**Example** ```javascript //find triples that are of type scm:Journey, and have //a start_station Start, and that start_station is labeled Start_Label @@ -87,29 +81,25 @@ WOQL.and( WOQL.triple(Start, "label", Start_Label)) ``` -## read\_object - -~~**WOQL.read\_object()**~~ - -_**Deprecated**_ +## read_object +##### ~~WOQL.read\_object()~~ +***Deprecated*** -Use [read\_document](woql.md#read\_document) instead. +Use [read_document](#read_document) instead. -## read\_document - -**WOQL.read\_document(IRI, output) ⇒ `object`** +## read_document +##### WOQL.read\_document(IRI, output) ⇒ object Read a node identified by an IRI as a JSON-LD document -**Returns**: `object` - WOQLQuery - -| Param | Type | Description | -| ------ | -------- | --------------------------------------------- | -| IRI | `string` | The document id or a variable to read | -| output | `string` | Variable which will be bound to the document. | +**Returns**: object - WOQLQuery -**Example** +| Param | Type | Description | +| --- | --- | --- | +| IRI | string | The document id or a variable to read | +| output | string | Variable which will be bound to the document. | +**Example** ```javascript let [person] = vars("Person") const query = WOQL.read_document( @@ -119,66 +109,58 @@ const query = WOQL.read_document( const res = await client.query(query); ``` -## insert\_document - -**WOQL.insert\_document(docjson, \[IRI]) ⇒ `object`** - +## insert_document +##### WOQL.insert\_document(docjson, [IRI]) ⇒ object Insert a document in the graph. -**Returns**: `object` - WOQLQuery +**Returns**: object - WOQLQuery -| Param | Type | Description | -| ------- | -------- | -------------------------------------------------------------------------------- | -| docjson | `object` | The document to insert. Must either have an '@id' or have a class specified key. | -| \[IRI] | `string` | An optional identifier specifying the document location. | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| docjson | object | The document to insert. Must either have an '@id' or have a class specified key. | +| [IRI] | string | An optional identifier specifying the document location. | +**Example** ```javascript const res = await client.query( WOQL.insert_document(WOQL.doc({ "@type" : "Person", "label": "John" })) ) ``` -## update\_document - -**WOQL.update\_document(docjson, \[IRI]) ⇒ `object`** - +## update_document +##### WOQL.update\_document(docjson, [IRI]) ⇒ object Update a document identified by an IRI -**Returns**: `object` - WOQLQuery - -| Param | Type | Description | -| ------- | -------- | -------------------------------------------------------------------------------- | -| docjson | `object` | The document to update. Must either have an '@id' or have a class specified key. | -| \[IRI] | `string` | An optional identifier specifying the document location. | +**Returns**: object - WOQLQuery -## delete\_document +| Param | Type | Description | +| --- | --- | --- | +| docjson | object | The document to update. Must either have an '@id' or have a class specified key. | +| [IRI] | string | An optional identifier specifying the document location. | -**WOQL.delete\_document(IRI) ⇒ `object`** +## delete_document +##### WOQL.delete\_document(IRI) ⇒ object Delete a document from the graph. -**Returns**: `object` - WOQLQuery +**Returns**: object - WOQLQuery -| Param | Type | Description | -| ----- | -------- | ----------------------------- | -| IRI | `string` | The document id or a variable | +| Param | Type | Description | +| --- | --- | --- | +| IRI | string | The document id or a variable | -## or - -**WOQL.or(...subqueries) ⇒ `WOQLQuery`** +## or +##### WOQL.or(...subqueries) ⇒ WOQLQuery Creates a logical OR of the arguments -**Returns**: `WOQLQuery` - - A WOQLQuery object containing the logical Or of the subqueries - -| Param | Type | Description | -| ------------- | ----------- | ------------------------------------------------------------- | -| ...subqueries | `WOQLQuery` | A list of one or more woql queries to execute as alternatives | +**Returns**: WOQLQuery - - A WOQLQuery object containing the logical Or of the subqueries -**Example** +| Param | Type | Description | +| --- | --- | --- | +| ...subqueries | WOQLQuery | A list of one or more woql queries to execute as alternatives | +**Example** ```javascript let [Subject] = vars("Subject") or( @@ -188,33 +170,29 @@ or( ``` ## from - -**WOQL.from(graphRef-, \[query]) ⇒ `WOQLQuery`** - +##### WOQL.from(graphRef-, [query]) ⇒ WOQLQuery Specifies the database URL that will be the default database for the enclosed query -**Returns**: `WOQLQuery` - A WOQLQuery object containing the from expression +**Returns**: WOQLQuery - A WOQLQuery object containing the from expression -| Param | Type | Description | -| --------- | ------------------ | ---------------------------------------- | -| graphRef- | `typedef.GraphRef` | A valid graph resource identifier string | -| \[query] | `WOQLQuery` | The query | +| Param | Type | Description | +| --- | --- | --- | +| graphRef- | typedef.GraphRef | A valid graph resource identifier string | +| [query] | WOQLQuery | The query | -## into - -**WOQL.into(graphRef-, \[subquery]) ⇒ `WOQLQuery`** +## into +##### WOQL.into(graphRef-, [subquery]) ⇒ WOQLQuery Specifies the graph resource to write the contained query into -**Returns**: `WOQLQuery` - A WOQLQuery which will be written into the graph in question +**Returns**: WOQLQuery - A WOQLQuery which will be written into the graph in question -| Param | Type | Description | -| ----------- | ------------------ | ---------------------------------------------- | -| graphRef- | `typedef.GraphRef` | A valid graph resource identifier string | -| \[subquery] | `WOQLQuery` | The query which will be written into the graph | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| graphRef- | typedef.GraphRef | A valid graph resource identifier string | +| [subquery] | WOQLQuery | The query which will be written into the graph | +**Example** ```javascript //Subq is an argument or a chained query using("admin/minecraft").into("instance/main").add_triple("a", "rdf:type", "@schema:X") @@ -222,135 +200,135 @@ using("admin/minecraft").into("instance/main").add_triple("a", "rdf:type", "@sch ``` ## triple +##### WOQL.triple(subject, predicate, object) ⇒ WOQLQuery +Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, Object) -**WOQL.triple(subject, predicate, object) ⇒ `WOQLQuery`** -Creates a triple pattern matching rule for the triple \[S, P, O] (Subject, Predicate, Object) +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | -| Param | Type | Description | -| --------- | ----------------- | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | -## added\_triple +## added_triple +##### WOQL.added\_triple(subject, predicate, object) ⇒ WOQLQuery +Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, +Object) added in the current layer -**WOQL.added\_triple(subject, predicate, object) ⇒ `WOQLQuery`** -Creates a triple pattern matching rule for the triple \[S, P, O] (Subject, Predicate, Object) added in the current layer +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | -| Param | Type | Description | -| --------- | ----------------- | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | -## removed\_triple +## removed_triple +##### WOQL.removed\_triple(subject, predicate, object) ⇒ WOQLQuery +Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate, +Object) added in the current commit -**WOQL.removed\_triple(subject, predicate, object) ⇒ `WOQLQuery`** -Creates a triple pattern matching rule for the triple \[S, P, O] (Subject, Predicate, Object) added in the current commit +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | -| Param | Type | Description | -| --------- | ----------------- | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | ## quad +##### WOQL.quad(subject, predicate, object, graphRef) ⇒ WOQLQuery +Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) -**WOQL.quad(subject, predicate, object, graphRef) ⇒ `WOQLQuery`** -Creates a pattern matching rule for the quad \[S, P, O, G] (Subject, Predicate, Object, Graph) +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | +| graphRef | typedef.GraphRef | A valid graph resource identifier string | -| Param | Type | Description | -| --------- | ------------------ | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | -| graphRef | `typedef.GraphRef` | A valid graph resource identifier string | -## added\_quad +## added_quad +##### WOQL.added\_quad(subject, predicate, object, graphRef-) ⇒ WOQLQuery +Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, +Object, Graph) removed from the current commit -**WOQL.added\_quad(subject, predicate, object, graphRef-) ⇒ `WOQLQuery`** -Creates a pattern matching rule for the quad \[S, P, O, G] (Subject, Predicate, Object, Graph) removed from the current commit +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | +| graphRef- | typedef.GraphRef | A valid graph resource identifier string | -| Param | Type | Description | -| --------- | ------------------ | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | -| graphRef- | `typedef.GraphRef` | A valid graph resource identifier string | -## removed\_quad +## removed_quad +##### WOQL.removed\_quad(subject, predicate, object, graphRef-) ⇒ WOQLQuery +Creates a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, +Object, Graph) removed from the current commit -**WOQL.removed\_quad(subject, predicate, object, graphRef-) ⇒ `WOQLQuery`** -Creates a pattern matching rule for the quad \[S, P, O, G] (Subject, Predicate, Object, Graph) removed from the current commit +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | +| graphRef- | typedef.GraphRef | A valid graph resource identifier string | -| Param | Type | Description | -| --------- | ------------------ | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | -| graphRef- | `typedef.GraphRef` | A valid graph resource identifier string | ## sub - -**WOQL.sub(classA, classB) ⇒ `boolean`** - +##### WOQL.sub(classA, classB) ⇒ boolean Returns true if ClassA subsumes ClassB, according to the current DB schema -**Returns**: `boolean` - WOQLQuery - -| Param | Type | Description | -| ------ | -------- | ----------- | -| classA | `string` | ClassA | -| classB | `string` | ClassB | +**Returns**: boolean - WOQLQuery -## eq +| Param | Type | Description | +| --- | --- | --- | +| classA | string | ClassA | +| classB | string | ClassB | -**WOQL.eq(varName, varValue) ⇒ `WOQLQuery`** +## eq +##### WOQL.eq(varName, varValue) ⇒ WOQLQuery Matches if a is equal to b -| Param | Type | Description | -| -------- | ----------------- | ----------------------- | -| varName | `string` \| `Var` | literal, variable or id | -| varValue | `string` \| `Var` | literal, variable or id | -## substr +| Param | Type | Description | +| --- | --- | --- | +| varName | string \| Var | literal, variable or id | +| varValue | string \| Var | literal, variable or id | -**WOQL.substr(string, before, \[length], \[after], \[substring]) ⇒ `WOQLQuery`** +## substr +##### WOQL.substr(string, before, [length], [after], [substring]) ⇒ WOQLQuery Substring -| Param | Type | Description | -| ------------ | ----------------- | ---------------------------------------------------------- | -| string | `string` \| `Var` | String or variable | -| before | `number` \| `Var` | integer or variable (characters from start to begin) | -| \[length] | `number` \| `Var` | integer or variable (length of substring) | -| \[after] | `number` \| `Var` | integer or variable (number of characters after substring) | -| \[substring] | `string` \| `Var` | String or variable | -## get +| Param | Type | Description | +| --- | --- | --- | +| string | string \| Var | String or variable | +| before | number \| Var | integer or variable (characters from start to begin) | +| [length] | number \| Var | integer or variable (length of substring) | +| [after] | number \| Var | integer or variable (number of characters after substring) | +| [substring] | string \| Var | String or variable | -~~**WOQL.get(asvars, queryResource) ⇒**** ****`WOQLQuery`**~~ -_**Deprecated**_ +## get +##### ~~WOQL.get(asvars, queryResource) ⇒ WOQLQuery~~ +***Deprecated*** Use the document inteface to import documents -**Returns**: `WOQLQuery` - A WOQLQuery which contains the get expression +**Returns**: WOQLQuery - A WOQLQuery which contains the get expression -| Param | Type | Description | -| ------------- | ----------------------- | ------------------------------------------------------------- | -| asvars | `Vars` \| `array.` | an array of AsVar variable mappings (see as for format below) | -| queryResource | `WOQLQuery` | an external resource (remote, file, post) to query | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| asvars | Vars \| array.<Var> | an array of AsVar variable mappings (see as for format below) | +| queryResource | WOQLQuery | an external resource (remote, file, post) to query | +**Example** ```javascript let [a, b] = vars("a", "b") get(as("a", a).as("b", b)).remote("http://my.url.com/x.csv") @@ -359,44 +337,33 @@ get(as("a", a).as("b", b)).remote("http://my.url.com/x.csv") ``` ## put - -~~**WOQL.put(varsToExp, query, fileResource) ⇒**** ****`WOQLQuery`**~~ - -_**Deprecated**_ +##### ~~WOQL.put(varsToExp, query, fileResource) ⇒ WOQLQuery~~ +***Deprecated*** Use the document inteface to import documents -**Returns**: `WOQLQuery` - A WOQLQuery which contains the put expression\ -**Put**: Outputs the results of a query to a file +**Returns**: WOQLQuery - A WOQLQuery which contains the put expression +**Put**: Outputs the results of a query to a file -| Param | Type | Description | -| ------------ | ----------------------- | ------------------------------------------------------------- | -| varsToExp | `Vars` \| `array.` | an array of AsVar variable mappings (see as for format below) | -| query | `WOQLQuery` | The query which will be executed to produce the results | -| fileResource | `string` | an file resource local to the server | +| Param | Type | Description | +| --- | --- | --- | +| varsToExp | Vars \| array.<Var> | an array of AsVar variable mappings (see as for format below) | +| query | WOQLQuery | The query which will be executed to produce the results | +| fileResource | string | an file resource local to the server | -**Example** - -```javascript -let [s, p, o] = vars("Subject", "Predicate", "Object") -WOQL.put(WOQL.as("s", s).as("p", p).as("o", o), WOQL.all()) -.file({file:"/app/local_files/dump.csv"}) -``` ## as - -**WOQL.as(source, target, \[type]) ⇒ `WOQLQuery`** - +##### WOQL.as(source, target, [type]) ⇒ WOQLQuery Imports the value identified by Source to a Target variable -| Param | Type | Description | -| ------- | ----------------------------- | ---------------------------- | -| source | `string` \| `number` \| `Var` | Source | -| target | `string` \| `Var` | Target | -| \[type] | `string` | type to cast value to string | -**Example** +| Param | Type | Description | +| --- | --- | --- | +| source | string \| number \| Var | Source | +| target | string \| Var | Target | +| [type] | string | type to cast value to string|number etc... | +**Example** ```javascript let [First_Var, Second_Var] = vars('First_Var', 'Second_Var') WOQL.as("first var", First_Var, "string").as("second var", Second_Var) @@ -404,126 +371,112 @@ WOQL.as(["first var", First_Var, "string"], ["second var", Second_Var]) ``` ## remote - -**WOQL.remote(remoteObj, \[formatObj]) ⇒ `WOQLQuery`** - +##### WOQL.remote(remoteObj, [formatObj]) ⇒ WOQLQuery Identifies a remote resource by URL and specifies the format of the resource through the options -**Returns**: `WOQLQuery` - A WOQLQuery which contains the remote resource identifier - -| Param | Type | Description | -| ------------ | ----------------------- | ---------------------------------------------------- | -| remoteObj | `object` | The URL at which the remote resource can be accessed | -| \[formatObj] | `typedef.DataFormatObj` | The format of the resource data {} | +**Returns**: WOQLQuery - A WOQLQuery which contains the remote resource identifier -**Example** +| Param | Type | Description | +| --- | --- | --- | +| remoteObj | object | The URL at which the remote resource can be accessed | +| [formatObj] | typedef.DataFormatObj | The format of the resource data {} | +**Example** ```javascript remote({url:"http://url.of.resource"}, {type: "csv"}) ``` ## post +##### WOQL.post(url, [formatObj], [source]) ⇒ WOQLQuery +Identifies a resource as a local path on the client, to be sent to the server through a +HTTP POST request, with the format defined through the options -**WOQL.post(url, \[formatObj], \[source]) ⇒ `WOQLQuery`** +**Returns**: WOQLQuery - A WOQLQuery which contains the Post resource identifier -Identifies a resource as a local path on the client, to be sent to the server through a HTTP POST request, with the format defined through the options - -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Post resource identifier - -| Param | Type | Description | -| ------------ | ----------------------- | ----------------------------------------------------------------- | -| url | `string` | The Path on the server at which the file resource can be accessed | -| \[formatObj] | `typedef.DataFormatObj` | imput options, optional | -| \[source] | `string` | It defines the source of the file, it can be 'url','post' | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| url | string | The Path on the server at which the file resource can be accessed | +| [formatObj] | typedef.DataFormatObj | imput options, optional | +| [source] | string | It defines the source of the file, it can be 'url','post' | +**Example** ```javascript post("/.../.../", {type:'csv'}) ``` -## delete\_triple - -**WOQL.delete\_triple(subject, predicate, object) ⇒ `WOQLQuery`** - +## delete_triple +##### WOQL.delete\_triple(subject, predicate, object) ⇒ WOQLQuery Deletes a single triple from the default graph of the database -**Returns**: `WOQLQuery` - - A WOQLQuery which contains the Triple Deletion statement - -| Param | Type | Description | -| --------- | ----------------- | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | +**Returns**: WOQLQuery - - A WOQLQuery which contains the Triple Deletion statement -**Example** +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | +**Example** ```javascript delete_triple("john", "age", 42) ``` -## delete\_quad - -**WOQL.delete\_quad(subject, predicate, object, graphRef) ⇒ `WOQLQuery`** +## delete_quad +##### WOQL.delete\_quad(subject, predicate, object, graphRef) ⇒ WOQLQuery +Deletes a single triple from the graph [Subject, Predicate, Object, Graph] -Deletes a single triple from the graph \[Subject, Predicate, Object, Graph] +**Returns**: WOQLQuery - - A WOQLQuery which contains the Delete Quad Statement -**Returns**: `WOQLQuery` - - A WOQLQuery which contains the Delete Quad Statement - -| Param | Type | Description | -| --------- | ------------------ | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | -| graphRef | `typedef.GraphRef` | A valid graph resource identifier string | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | +| graphRef | typedef.GraphRef | A valid graph resource identifier string | +**Example** ```javascript remove the class Person from the schema graph WOQL.delete_quad("Person", "rdf:type", "sys:Class", "schema") ``` -## add\_triple +## add_triple +##### WOQL.add\_triple(subject, predicate, object) ⇒ WOQLQuery +Adds triples according to the the pattern [subject,predicate,object] -**WOQL.add\_triple(subject, predicate, object) ⇒ `WOQLQuery`** -Adds triples according to the the pattern \[subject,predicate,object] +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | -| Param | Type | Description | -| --------- | ----------------- | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | -## add\_quad +## add_quad +##### WOQL.add\_quad(subject, predicate, object, graphRef-) ⇒ WOQLQuery +Adds quads according to the pattern [S,P,O,G] -**WOQL.add\_quad(subject, predicate, object, graphRef-) ⇒ `WOQLQuery`** -Adds quads according to the pattern \[S,P,O,G] +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | +| graphRef- | typedef.GraphRef | A valid graph resource identifier string | -| Param | Type | Description | -| --------- | ------------------ | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | -| graphRef- | `typedef.GraphRef` | A valid graph resource identifier string | ## trim - -**WOQL.trim(inputStr, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.trim(inputStr, resultVarName) ⇒ WOQLQuery Remove whitespace from both sides of a string: -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Trim pattern matching expression +**Returns**: WOQLQuery - A WOQLQuery which contains the Trim pattern matching expression -| Param | Type | Description | -| ------------- | ----------------- | ------------------------------------------------------------------- | -| inputStr | `string` \| `Var` | A string or variable containing the untrimmed version of the string | -| resultVarName | `string` \| `Var` | A string or variable containing the trimmed version of the string | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| inputStr | string \| Var | A string or variable containing the untrimmed version of the string | +| resultVarName | string \| Var | A string or variable containing the trimmed version of the string | +**Example** ```javascript let [trimmed] = vars("trimmed") trim("hello ", trimmed) @@ -531,90 +484,77 @@ trim("hello ", trimmed) ``` ## evaluate - -**WOQL.evaluate(arithExp, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.evaluate(arithExp, resultVarName) ⇒ WOQLQuery Evaluates the passed arithmetic expression and generates or matches the result value -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Arithmetic function - -| Param | Type | Description | -| ------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| arithExp | `object` \| `WOQLQuery` \| `string` | A WOQL query containing a valid WOQL Arithmetic Expression, which is evaluated by the function | -| resultVarName | `string` \| `number` \| `Var` | Either a variable, in which the result of the expression will be stored, or a numeric literal which will be used as a test of result of the evaluated expression | +**Returns**: WOQLQuery - A WOQLQuery which contains the Arithmetic function -**Example** +| Param | Type | Description | +| --- | --- | --- | +| arithExp | object \| WOQLQuery \| string | A WOQL query containing a valid WOQL Arithmetic Expression, which is evaluated by the function | +| resultVarName | string \| number \| Var | Either a variable, in which the result of the expression will be stored, or a numeric literal which will be used as a test of result of the evaluated expression | +**Example** ```javascript let [result] = vars("result") evaluate(plus(2, minus(3, 1)), result) ``` ## eval - -**WOQL.eval(arithExp, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.eval(arithExp, resultVarName) ⇒ WOQLQuery Evaluates the passed arithmetic expression and generates or matches the result value -**Returns**: `WOQLQuery` - WOQLQuery +**Returns**: WOQLQuery - WOQLQuery -| Param | Type | Description | -| ------------- | ----------------------------------- | --------------------------------------- | -| arithExp | `object` \| `WOQLQuery` \| `string` | query or JSON-LD representing the query | -| resultVarName | `string` \| `Var` | output variable | - -## plus +| Param | Type | Description | +| --- | --- | --- | +| arithExp | object \| WOQLQuery \| string | query or JSON-LD representing the query | +| resultVarName | string \| Var | output variable | -**WOQL.plus(...args) ⇒ `WOQLQuery`** +## plus +##### WOQL.plus(...args) ⇒ WOQLQuery Adds the numbers together -**Returns**: `WOQLQuery` - A WOQLQuery which contains the addition expression - -| Param | Type | Description | -| ------- | ----------------------------- | -------------------------------------------------- | -| ...args | `string` \| `number` \| `Var` | a variable or numeric containing the values to add | +**Returns**: WOQLQuery - A WOQLQuery which contains the addition expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| ...args | string \| number \| Var | a variable or numeric containing the values to add | +**Example** ```javascript let [result] = vars("result") evaluate(plus(2, plus(3, 1)), result) ``` ## minus - -**WOQL.minus(...args) ⇒ `WOQLQuery`** - +##### WOQL.minus(...args) ⇒ WOQLQuery Subtracts Numbers N1..Nn -**Returns**: `WOQLQuery` - A WOQLQuery which contains the subtraction expression +**Returns**: WOQLQuery - A WOQLQuery which contains the subtraction expression -| Param | Type | Description | -| ------- | ----------------------------- | --------------------------------------------------------------------- | -| ...args | `string` \| `number` \| `Var` | variable or numeric containing the value that will be subtracted from | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| ...args | string \| number \| Var | variable or numeric containing the value that will be subtracted from | +**Example** ```javascript let [result] = vars("result") evaluate(minus(2.1, plus(0.2, 1)), result) ``` ## times - -**WOQL.times(...args) ⇒ `WOQLQuery`** - +##### WOQL.times(...args) ⇒ WOQLQuery Multiplies numbers N1...Nn together -**Returns**: `WOQLQuery` - A WOQLQuery which contains the multiplication expression - -| Param | Type | Description | -| ------- | ----------------------------- | ------------------------------------------ | -| ...args | `string` \| `number` \| `Var` | a variable or numeric containing the value | +**Returns**: WOQLQuery - A WOQLQuery which contains the multiplication expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| ...args | string \| number \| Var | a variable or numeric containing the value | +**Example** ```javascript let [result] = vars("result") evaluate(times(10, minus(2.1, plus(0.2, 1))), result) @@ -622,31 +562,30 @@ evaluate(times(10, minus(2.1, plus(0.2, 1))), result) ``` ## divide - -**WOQL.divide(...args) ⇒ `WOQLQuery`** - +##### WOQL.divide(...args) ⇒ WOQLQuery Divides numbers N1...Nn by each other left, to right precedence -**Returns**: `WOQLQuery` - A WOQLQuery which contains the division expression let \[result] = vars("result") evaluate(divide(times(10, minus(2.1, plus(0.2, 1))), 10), result) //result contains 0.9000000000000001 +**Returns**: WOQLQuery - A WOQLQuery which contains the division expression +let [result] = vars("result") +evaluate(divide(times(10, minus(2.1, plus(0.2, 1))), 10), result) + //result contains 0.9000000000000001 -| Param | Type | Description | -| ------- | ----------------------------- | ---------------------- | -| ...args | `string` \| `number` \| `Var` | numbers to tbe divided | +| Param | Type | Description | +| --- | --- | --- | +| ...args | string \| number \| Var | numbers to tbe divided | -## div - -**WOQL.div(...args) ⇒ `WOQLQuery`** +## div +##### WOQL.div(...args) ⇒ WOQLQuery Division - integer division - args are divided left to right -**Returns**: `WOQLQuery` - A WOQLQuery which contains the division expression +**Returns**: WOQLQuery - A WOQLQuery which contains the division expression -| Param | Type | Description | -| ------- | ----------------------------- | -------------------- | -| ...args | `string` \| `number` \| `Var` | numbers for division | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| ...args | string \| number \| Var | numbers for division | +**Example** ```javascript let [result] = vars("result") evaluate(div(10, 3), result) @@ -654,20 +593,17 @@ evaluate(div(10, 3), result) ``` ## exp - -**WOQL.exp(varNum, expNum) ⇒ `WOQLQuery`** - +##### WOQL.exp(varNum, expNum) ⇒ WOQLQuery Exponent - raises varNum01 to the power of varNum02 -**Returns**: `WOQLQuery` - A WOQLQuery which contains the exponent expression - -| Param | Type | Description | -| ------ | ----------------------------- | ------------------------------------------------------------------------------------------ | -| varNum | `string` \| `number` \| `Var` | a variable or numeric containing the number to be raised to the power of the second number | -| expNum | `number` | a variable or numeric containing the exponent | +**Returns**: WOQLQuery - A WOQLQuery which contains the exponent expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varNum | string \| number \| Var | a variable or numeric containing the number to be raised to the power of the second number | +| expNum | number | a variable or numeric containing the exponent | +**Example** ```javascript let [result] = vars("result") evaluate(exp(3, 2), result) @@ -675,19 +611,16 @@ evaluate(exp(3, 2), result) ``` ## floor - -**WOQL.floor(varNum) ⇒ `WOQLQuery`** - +##### WOQL.floor(varNum) ⇒ WOQLQuery Generates the nearest lower integer to the passed number -**Returns**: `WOQLQuery` - A WOQLQuery which contains the floor expression - -| Param | Type | Description | -| ------ | ----------------------------- | ------------------------------------------------------- | -| varNum | `string` \| `number` \| `Var` | Variable or numeric containing the number to be floored | +**Returns**: WOQLQuery - A WOQLQuery which contains the floor expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varNum | string \| number \| Var | Variable or numeric containing the number to be floored | +**Example** ```javascript let [result] = vars("result") evaluate(divide(floor(times(10, minus(2.1, plus(0.2, 1)))), 10), result) @@ -695,41 +628,35 @@ evaluate(divide(floor(times(10, minus(2.1, plus(0.2, 1)))), 10), result) ``` ## isa - -**WOQL.isa(instanceIRI, classId) ⇒ `WOQLQuery`** - +##### WOQL.isa(instanceIRI, classId) ⇒ WOQLQuery Tests whether a given instance IRI has type Class, according to the current state of the DB -**Returns**: `WOQLQuery` - A WOQLQuery object containing the type test +**Returns**: WOQLQuery - A WOQLQuery object containing the type test -| Param | Type | Description | -| ----------- | ----------------- | ----------------------------------------------------------- | -| instanceIRI | `string` \| `Var` | A string IRI or a variable that identify the class instance | -| classId | `string` \| `Var` | A Class IRI or a variable | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| instanceIRI | string \| Var | A string IRI or a variable that identify the class instance | +| classId | string \| Var | A Class IRI or a variable | +**Example** ```javascript let [subject] = vars("subject") isa(subject, "Person") ``` ## like - -**WOQL.like(stringA, stringB, distance) ⇒ `WOQLQuery`** - +##### WOQL.like(stringA, stringB, distance) ⇒ WOQLQuery Generates a string Leverstein distance measure between stringA and stringB -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Like pattern matching expression - -| Param | Type | Description | -| -------- | ----------------------------- | ----------------------------------------------------------------------- | -| stringA | `string` \| `Var` | string literal or variable representing a string to be compared | -| stringB | `string` \| `Var` | string literal or variable representing the other string to be compared | -| distance | `number` \| `string` \| `Var` | variable representing the distance between the variables | +**Returns**: WOQLQuery - A WOQLQuery which contains the Like pattern matching expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| stringA | string \| Var | string literal or variable representing a string to be compared | +| stringB | string \| Var | string literal or variable representing the other string to be compared | +| distance | number \| string \| Var | variable representing the distance between the variables | +**Example** ```javascript let [dist] = vars('dist') like("hello", "hallo", dist) @@ -737,20 +664,17 @@ like("hello", "hallo", dist) ``` ## less - -**WOQL.less(varNum01, varNum02) ⇒ `WOQLQuery`** - +##### WOQL.less(varNum01, varNum02) ⇒ WOQLQuery Compares the value of v1 against v2 and returns true if v1 is less than v2 -**Returns**: `WOQLQuery` - A WOQLQuery which contains the comparison expression +**Returns**: WOQLQuery - A WOQLQuery which contains the comparison expression -| Param | Type | Description | -| -------- | ----------------------------- | ---------------------------------------------------------- | -| varNum01 | `string` \| `number` \| `Var` | a variable or numeric containing the number to be compared | -| varNum02 | `string` \| `number` \| `Var` | a variable or numeric containing the second comporator | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varNum01 | string \| number \| Var | a variable or numeric containing the number to be compared | +| varNum02 | string \| number \| Var | a variable or numeric containing the second comporator | +**Example** ```javascript let [result] = vars("result") less(1, 1.1).eq(result, literal(true, "boolean")) @@ -758,20 +682,17 @@ less(1, 1.1).eq(result, literal(true, "boolean")) ``` ## greater - -**WOQL.greater(varNum01, varNum02) ⇒ `WOQLQuery`** - +##### WOQL.greater(varNum01, varNum02) ⇒ WOQLQuery Compares the value of v1 against v2 and returns true if v1 is greater than v2 -**Returns**: `WOQLQuery` - A WOQLQuery which contains the comparison expression - -| Param | Type | Description | -| -------- | ----------------------------- | ---------------------------------------------------------- | -| varNum01 | `string` \| `number` \| `Var` | a variable or numeric containing the number to be compared | -| varNum02 | `string` \| `number` \| `Var` | a variable or numeric containing the second comporator | +**Returns**: WOQLQuery - A WOQLQuery which contains the comparison expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varNum01 | string \| number \| Var | a variable or numeric containing the number to be compared | +| varNum02 | string \| number \| Var | a variable or numeric containing the second comporator | +**Example** ```javascript let [result] = vars("result") greater(1.2, 1.1).eq(result, literal(true, "boolean")) @@ -779,19 +700,16 @@ greater(1.2, 1.1).eq(result, literal(true, "boolean")) ``` ## opt - -**WOQL.opt(\[subquery]) ⇒ `WOQLQuery`** - +##### WOQL.opt([subquery]) ⇒ WOQLQuery Specifies that the Subquery is optional - if it does not match the query will not fail -**Returns**: `WOQLQuery` - A WOQLQuery object containing the optional sub Query - -| Param | Type | Description | -| ----------- | ----------- | ------------------------------------------- | -| \[subquery] | `WOQLQuery` | A subquery which will be optionally matched | +**Returns**: WOQLQuery - A WOQLQuery object containing the optional sub Query -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [subquery] | WOQLQuery | A subquery which will be optionally matched | +**Example** ```javascript let [subject] = vars("subject") opt(triple(subject, 'label', "A")) @@ -800,62 +718,54 @@ opt().triple(subject, 'label', "A") ``` ## unique +##### WOQL.unique(prefix, inputVarList, resultVarName) ⇒ WOQLQuery +Generate a new IRI from the prefix and a hash of the variables which will be unique for any +given combination of variables -**WOQL.unique(prefix, inputVarList, resultVarName) ⇒ `WOQLQuery`** - -Generate a new IRI from the prefix and a hash of the variables which will be unique for any given combination of variables - -**Returns**: `WOQLQuery` - A WOQLQuery object containing the unique ID generating function +**Returns**: WOQLQuery - A WOQLQuery object containing the unique ID generating function -| Param | Type | Description | -| ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- | -| prefix | `string` | A prefix for the IRI - typically formed of the doc prefix and the classtype of the entity (“doc:Person”) | -| inputVarList | `array` \| `string` \| `Var` | An array of variables and / or strings from which the unique hash will be generated | -| resultVarName | `string` \| `Var` | Variable in which the unique ID is stored | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| prefix | string | A prefix for the IRI - typically formed of the doc prefix and the classtype of the entity (“doc:Person”) | +| inputVarList | array \| string \| Var | An array of variables and / or strings from which the unique hash will be generated | +| resultVarName | string \| Var | Variable in which the unique ID is stored | +**Example** ```javascript let [newid] = vars("newid") unique("doc:Person", ["John", "Smith"], newid) ``` ## idgen - -**WOQL.idgen(prefix, inputVarList, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.idgen(prefix, inputVarList, resultVarName) ⇒ WOQLQuery Generate a new IRI from the prefix and concatention of the variables -**Returns**: `WOQLQuery` - A WOQLQuery object containing the ID generating function - -| Param | Type | Description | -| ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- | -| prefix | `string` | A prefix for the IRI - typically formed of the doc prefix and the classtype of the entity (“doc:Person”) | -| inputVarList | `array` \| `string` \| `Var` | An array of variables and / or strings from which the unique hash will be generated | -| resultVarName | `string` \| `Var` | Variable in which the unique ID is stored | +**Returns**: WOQLQuery - A WOQLQuery object containing the ID generating function -**Example** +| Param | Type | Description | +| --- | --- | --- | +| prefix | string | A prefix for the IRI - typically formed of the doc prefix and the classtype of the entity (“doc:Person”) | +| inputVarList | array \| string \| Var | An array of variables and / or strings from which the unique hash will be generated | +| resultVarName | string \| Var | Variable in which the unique ID is stored | +**Example** ```javascript let [newid] = vars("newid") idgen("doc:Person", ["John", "Smith"], newid) ``` ## upper - -**WOQL.upper(inputVarName, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.upper(inputVarName, resultVarName) ⇒ WOQLQuery Changes a string to upper-case -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Upper case pattern matching expression +**Returns**: WOQLQuery - A WOQLQuery which contains the Upper case pattern matching expression -| Param | Type | Description | -| ------------- | ----------------- | -------------------------------------------------------- | -| inputVarName | `string` \| `Var` | string or variable representing the uncapitalized string | -| resultVarName | `string` \| `Var` | variable that stores the capitalized string output | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| inputVarName | string \| Var | string or variable representing the uncapitalized string | +| resultVarName | string \| Var | variable that stores the capitalized string output | +**Example** ```javascript let [allcaps] = vars("allcaps") upper("aBCe", allcaps) @@ -863,20 +773,17 @@ upper("aBCe", allcaps) ``` ## lower - -**WOQL.lower(inputVarName, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.lower(inputVarName, resultVarName) ⇒ WOQLQuery Changes a string to lower-case -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Lower case pattern matching expression - -| Param | Type | Description | -| ------------- | ----------------- | --------------------------------------------------------- | -| inputVarName | `string` \| `Var` | string or variable representing the non-lowercased string | -| resultVarName | `string` \| `Var` | variable that stores the lowercased string output | +**Returns**: WOQLQuery - A WOQLQuery which contains the Lower case pattern matching expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| inputVarName | string \| Var | string or variable representing the non-lowercased string | +| resultVarName | string \| Var | variable that stores the lowercased string output | +**Example** ```javascript let [lower] = var("l") lower("aBCe", lower) @@ -884,22 +791,20 @@ lower("aBCe", lower) ``` ## pad +##### WOQL.pad(inputVarName, pad, len, resultVarName) ⇒ WOQLQuery +Pads out the string input to be exactly len long by appending the pad character pad to +form output -**WOQL.pad(inputVarName, pad, len, resultVarName) ⇒ `WOQLQuery`** - -Pads out the string input to be exactly len long by appending the pad character pad to form output +**Returns**: WOQLQuery - A WOQLQuery which contains the Pad pattern matching expression -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Pad pattern matching expression - -| Param | Type | Description | -| ------------- | ----------------------------- | -------------------------------------------------------------------------- | -| inputVarName | `string` \| `Var` | The input string or variable in unpadded state | -| pad | `string` \| `Var` | The characters to use to pad the string or a variable representing them | -| len | `number` \| `string` \| `Var` | The variable or integer value representing the length of the output string | -| resultVarName | `string` \| `Var` | stores output | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| inputVarName | string \| Var | The input string or variable in unpadded state | +| pad | string \| Var | The characters to use to pad the string or a variable representing them | +| len | number \| string \| Var | The variable or integer value representing the length of the output string | +| resultVarName | string \| Var | stores output | +**Example** ```javascript let [fixed] = vars("fixed length") pad("joe", " ", 8, fixed) @@ -907,142 +812,125 @@ pad("joe", " ", 8, fixed) ``` ## split - -**WOQL.split(inputVarName, separator, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.split(inputVarName, separator, resultVarName) ⇒ WOQLQuery Splits a string (Input) into a list strings (Output) by removing separator -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Split pattern matching expression +**Returns**: WOQLQuery - A WOQLQuery which contains the Split pattern matching expression -| Param | Type | Description | -| ------------- | ----------------- | ------------------------------------------------------------------------------- | -| inputVarName | `string` \| `Var` | A string or variable representing the unsplit string | -| separator | `string` \| `Var` | A string or variable containing a sequence of charatcters to use as a separator | -| resultVarName | `string` \| `Var` | variable that stores output list | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| inputVarName | string \| Var | A string or variable representing the unsplit string | +| separator | string \| Var | A string or variable containing a sequence of charatcters to use as a separator | +| resultVarName | string \| Var | variable that stores output list | +**Example** ```javascript let [words] = vars("words") split("joe has a hat", " ", words) ``` ## member - -**WOQL.member(element, list) ⇒ `WOQLQuery`** - +##### WOQL.member(element, list) ⇒ WOQLQuery Matches if List includes Element -**Returns**: `WOQLQuery` - A WOQLQuery which contains the List inclusion pattern matching expression - -| Param | Type | Description | -| ------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------- | -| element | `string` \| `object` \| `Var` | Either a variable, IRI or any simple datatype | -| list | `string` \| `array` \| `Var` | List (\[string, literal] or string\*) Either a variable representing a list or a list of variables or literals | +**Returns**: WOQLQuery - A WOQLQuery which contains the List inclusion pattern matching expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| element | string \| object \| Var | Either a variable, IRI or any simple datatype | +| list | string \| array \| Var | List ([string, literal] or string*) Either a variable representing a list or a list of variables or literals | +**Example** ```javascript let [name] = vars("name") member(name, ["john", "joe", "frank"]) ``` ## concat - -**WOQL.concat(varList, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.concat(varList, resultVarName) ⇒ WOQLQuery takes a variable number of string arguments and concatenates them into a single string -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Concatenation pattern matching expression +**Returns**: WOQLQuery - A WOQLQuery which contains the Concatenation pattern matching expression -| Param | Type | Description | -| ------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| varList | `array` \| `string` \| `Var` | a variable representing a list or a list of variables or strings - variables can be embedded in the string if they do not contain spaces | -| resultVarName | `string` \| `Var` | A variable or string containing the output string | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varList | array \| string \| Var | a variable representing a list or a list of variables or strings - variables can be embedded in the string if they do not contain spaces | +| resultVarName | string \| Var | A variable or string containing the output string | +**Example** ```javascript let [first_name, last_name, full_name] = vars("first_name", "last_name", "full_name") concat([first_name, " ", last_name], full_name) ``` ## join +##### WOQL.join(varList, glue, resultVarName) ⇒ WOQLQuery +Joins a list variable together (Input) into a string variable (Output) by glueing the strings +together with Glue -**WOQL.join(varList, glue, resultVarName) ⇒ `WOQLQuery`** - -Joins a list variable together (Input) into a string variable (Output) by glueing the strings together with Glue +**Returns**: WOQLQuery - A WOQLQuery which contains the Join pattern matching expression -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Join pattern matching expression - -| Param | Type | Description | -| ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- | -| varList | `string` \| `array` \| `Var` | a variable representing a list or a list of strings and / or variables | -| glue | `string` \| `Var` | A variable (v:glue) or (glue) string representing the characters to put in between the joined strings in input | -| resultVarName | `string` \| `Var` | A variable or string containing the output string | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varList | string \| array \| Var | a variable representing a list or a list of strings and / or variables | +| glue | string \| Var | A variable (v:glue) or (glue) string representing the characters to put in between the joined strings in input | +| resultVarName | string \| Var | A variable or string containing the output string | +**Example** ```javascript let [sentence] = vars("sentence") join(["joe", "has", "a", "hat", " ", sentence) ``` ## sum +##### WOQL.sum(subquery, total) ⇒ WOQLQuery +computes the sum of the List of values passed. In contrast to other arithmetic functions, +sum self-evaluates - it does not have to be passed to evaluate() -**WOQL.sum(subquery, total) ⇒ `WOQLQuery`** - -computes the sum of the List of values passed. In contrast to other arithmetic functions, sum self-evaluates - it does not have to be passed to evaluate() - -**Returns**: `WOQLQuery` - - A WOQLQuery which contains the Sum expression +**Returns**: WOQLQuery - - A WOQLQuery which contains the Sum expression -| Param | Type | Description | -| -------- | ----------------- | -------------------------------------------------------------------------------------------------- | -| subquery | `WOQLQuery` | a subquery or (\[string or numeric]) - a list variable, or a list of variables or numeric literals | -| total | `string` \| `Var` | the variable name with the sum result of the values in List | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| subquery | WOQLQuery | a subquery or ([string or numeric]) - a list variable, or a list of variables or numeric literals | +| total | string \| Var | the variable name with the sum result of the values in List | +**Example** ```javascript let [total] = vars("total") sum([2, 3, 4, 5], total) ``` ## start - -**WOQL.start(start, \[subquery]) ⇒ `WOQLQuery`** - +##### WOQL.start(start, [subquery]) ⇒ WOQLQuery Specifies an offset position in the results to start listing results from -**Returns**: `WOQLQuery` - A WOQLQuery whose results will be returned starting from the specified offset - -| Param | Type | Description | -| ----------- | ----------------------------- | ---------------------------------------------------------------------------- | -| start | `number` \| `string` \| `Var` | A variable that refers to an interger or an integer literal | -| \[subquery] | `WOQLQuery` | WOQL Query object, you can pass a subquery as an argument or a chained query | +**Returns**: WOQLQuery - A WOQLQuery whose results will be returned starting from +the specified offset -**Example** +| Param | Type | Description | +| --- | --- | --- | +| start | number \| string \| Var | A variable that refers to an interger or an integer literal | +| [subquery] | WOQLQuery | WOQL Query object, you can pass a subquery as an argument or a chained query | +**Example** ```javascript let [a, b, c] = vars("a", "b", "c") start(100).triple(a, b, c) ``` ## limit - -**WOQL.limit(limit, \[subquery]) ⇒ `WOQLQuery`** - +##### WOQL.limit(limit, [subquery]) ⇒ WOQLQuery Specifies a maximum number of results that will be returned from the subquery -**Returns**: `WOQLQuery` - A WOQLQuery whose results will be returned starting from the specified offset +**Returns**: WOQLQuery - A WOQLQuery whose results will be returned starting from +the specified offset -| Param | Type | Description | -| ----------- | -------------------- | --------------------------------------------------------------------------- | -| limit | `number` \| `string` | A variable that refers to an non-negative integer or a non-negative integer | -| \[subquery] | `WOQLQuery` | A subquery whose results will be limited | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| limit | number \| string | A variable that refers to an non-negative integer or a non-negative integer | +| [subquery] | WOQLQuery | A subquery whose results will be limited | +**Example** ```javascript let [a, b, c] = vars("a", "b", "c") limit(100).triple(a, b, c) @@ -1051,21 +939,20 @@ limit(100,triple(a, b, c)) ``` ## re +##### WOQL.re(pattern, inputVarName, resultVarList) ⇒ WOQLQuery +Matches the regular expression defined in Patern against the Test string, to produce +the matched patterns in Matches -**WOQL.re(pattern, inputVarName, resultVarList) ⇒ `WOQLQuery`** - -Matches the regular expression defined in Patern against the Test string, to produce the matched patterns in Matches +**Returns**: WOQLQuery - A WOQLQuery which contains the Regular Expression pattern +matching expression -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Regular Expression pattern matching expression - -| Param | Type | Description | -| ------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| pattern | `string` | string or variable using normal PCRE regular expression syntax with the exception that special characters have to be escaped twice (to enable transport in JSONLD) | -| inputVarName | `string` \| `Var` | string or variable containing the string to be tested for patterns with the regex | -| resultVarList | `string` \| `array` \| `object` \| `Var` | variable representing the list of matches or a list of strings or variables | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| pattern | string | string or variable using normal PCRE regular expression syntax with the exception that special characters have to be escaped twice (to enable transport in JSONLD) | +| inputVarName | string \| Var | string or variable containing the string to be tested for patterns with the regex | +| resultVarList | string \| array \| object \| Var | variable representing the list of matches or a list of strings or variables | +**Example** ```javascript let [All, Sub] = vars("All", "Sub") WOQL.re("h(.).*", "hello", [All, Sub]) @@ -1076,145 +963,127 @@ and m is a list of matches: ``` ## length - -**WOQL.length(inputVarList, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.length(inputVarList, resultVarName) ⇒ WOQLQuery Calculates the length of the list in va and stores it in vb -**Returns**: `WOQLQuery` - A WOQLQuery which contains the Length pattern matching expression +**Returns**: WOQLQuery - A WOQLQuery which contains the Length pattern matching expression -| Param | Type | Description | -| ------------- | ------------------- | -------------------------------------------------------------------------------------------------------- | -| inputVarList | `string` \| `array` | Either a variable representing a list or a list of variables or literals | -| resultVarName | `string` \| `Var` | A variable in which the length of the list is stored or the length of the list as a non-negative integer | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| inputVarList | string \| array | Either a variable representing a list or a list of variables or literals | +| resultVarName | string \| Var | A variable in which the length of the list is stored or the length of the list as a non-negative integer | +**Example** ```javascript let [count] = vars("count") length(["john", "joe", "frank"], count) ``` ## not +##### WOQL.not([subquery]) ⇒ WOQLQuery +Logical negation of the contained subquery - if the subquery matches, the query +will fail to match -**WOQL.not(\[subquery]) ⇒ `WOQLQuery`** - -Logical negation of the contained subquery - if the subquery matches, the query will fail to match - -**Returns**: `WOQLQuery` - A WOQLQuery object containing the negated sub Query +**Returns**: WOQLQuery - A WOQLQuery object containing the negated sub Query -| Param | Type | Description | -| ----------- | ----------------------- | -------------------------------- | -| \[subquery] | `string` \| `WOQLQuery` | A subquery which will be negated | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [subquery] | string \| WOQLQuery | A subquery which will be negated | +**Example** ```javascript let [subject, label] = vars("subject", "label") not().triple(subject, 'label', label) ``` ## once - -**WOQL.once(\[subquery]) ⇒ `WOQLQuery`** - +##### WOQL.once([subquery]) ⇒ WOQLQuery Results in one solution of the subqueries -**Returns**: `WOQLQuery` - A WOQLQuery object containing the once sub Query - -| Param | Type | Description | -| ----------- | ----------------------- | ------------------ | -| \[subquery] | `string` \| `WOQLQuery` | WOQL Query objects | +**Returns**: WOQLQuery - A WOQLQuery object containing the once sub Query -## immediately +| Param | Type | Description | +| --- | --- | --- | +| [subquery] | string \| WOQLQuery | WOQL Query objects | -**WOQL.immediately(\[subquery]) ⇒ `WOQLQuery`** +## immediately +##### WOQL.immediately([subquery]) ⇒ WOQLQuery Runs the query without backtracking on side-effects -**Returns**: `WOQLQuery` - A WOQLQuery object containing the immediately sub Query +**Returns**: WOQLQuery - A WOQLQuery object containing the immediately sub Query -| Param | Type | Description | -| ----------- | ----------------------- | ------------------ | -| \[subquery] | `string` \| `WOQLQuery` | WOQL Query objects | - -## count +| Param | Type | Description | +| --- | --- | --- | +| [subquery] | string \| WOQLQuery | WOQL Query objects | -**WOQL.count(countVarName, \[subquery]) ⇒ `WOQLQuery`** +## count +##### WOQL.count(countVarName, [subquery]) ⇒ WOQLQuery Creates a count of the results of the query -**Returns**: `WOQLQuery` - A WOQLQuery object containing the count sub Query - -| Param | Type | Description | -| ------------ | ----------------------------- | ------------------------- | -| countVarName | `string` \| `number` \| `Var` | variable or integer count | -| \[subquery] | `WOQLQuery` | | +**Returns**: WOQLQuery - A WOQLQuery object containing the count sub Query -**Example** +| Param | Type | Description | +| --- | --- | --- | +| countVarName | string \| number \| Var | variable or integer count | +| [subquery] | WOQLQuery | | +**Example** ```javascript let [count, Person] = vars("count", "Person") WOQL.count(count).triple(Person, "rdf:type", "@schema:Person") ``` ## typecast - -**WOQL.typecast(varName, varType, resultVarName) ⇒ `WOQLQuery`** - +##### WOQL.typecast(varName, varType, resultVarName) ⇒ WOQLQuery Casts the value of Input to a new value of type Type and stores the result in CastVar -**Returns**: `WOQLQuery` - A WOQLQuery which contains the casting expression +**Returns**: WOQLQuery - A WOQLQuery which contains the casting expression -| Param | Type | Description | -| ------------- | ----------------------------------------- | ------------------------------------------------------- | -| varName | `string` \| `number` \| `object` \| `Var` | Either a single variable or a literal of any basic type | -| varType | `string` \| `Var` | Either a variable or a basic datatype (xsd / xdd) | -| resultVarName | `string` \| `Var` | save the return variable | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varName | string \| number \| object \| Var | Either a single variable or a literal of any basic type | +| varType | string \| Var | Either a variable or a basic datatype (xsd / xdd) | +| resultVarName | string \| Var | save the return variable | +**Example** ```javascript let [time] = vars("time") cast("22/3/98", "xsd:dateTime", time) ``` -## order\_by - -**WOQL.order\_by(varNames) ⇒ `WOQLQuery`** - +## order_by +##### WOQL.order\_by(varNames) ⇒ WOQLQuery Orders the results of the contained subquery by a precedence list of variables -**Returns**: `WOQLQuery` - A WOQLQuery which contains the ordering expression +**Returns**: WOQLQuery - A WOQLQuery which contains the ordering expression -| Param | Type | Description | -| -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| varNames | `string` \| `Var` \| `array` | A sequence of variables, by which to order the results, each optionally followed by either “asc” or “desc” to represent order as a list, by default it will sort the variable in ascending order | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varNames | string \| Var \| array | A sequence of variables, by which to order the results, each optionally followed by either “asc” or “desc” to represent order as a list, by default it will sort the variable in ascending order | +**Example** ```javascript let [A, B, C] = vars("A", "B", "C") WOQL.order_by(A, [B, "asc"], [C, "desc"]).triple(A, B, C); ``` -## group\_by - -**WOQL.group\_by(varList, patternVars, resultVarName, \[subquery]) ⇒ `WOQLQuery`** - -Groups the results of the contained subquery on the basis of identical values for Groupvars, extracts the patterns defined in PatternVars and stores the results in GroupedVar - -**Returns**: `WOQLQuery` - A WOQLQuery which contains the grouping expression +## group_by +##### WOQL.group\_by(varList, patternVars, resultVarName, [subquery]) ⇒ WOQLQuery +Groups the results of the contained subquery on the basis of identical values for Groupvars, +extracts the patterns defined in PatternVars and stores the results in GroupedVar -| Param | Type | Description | -| ------------- | ---------------------------- | ------------------------------------------------- | -| varList | `array` \| `string` \| `Var` | Either a single variable or an array of variables | -| patternVars | `array` \| `string` \| `Var` | Either a single variable or an array of variables | -| resultVarName | `string` \| `Var` | output variable name | -| \[subquery] | `WOQLQuery` | The query whose results will be grouped | +**Returns**: WOQLQuery - A WOQLQuery which contains the grouping expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| varList | array \| string \| Var | Either a single variable or an array of variables | +| patternVars | array \| string \| Var | Either a single variable or an array of variables | +| resultVarName | string \| Var | output variable name | +| [subquery] | WOQLQuery | The query whose results will be grouped | +**Example** ```javascript //subquery is an argument or a chained query let [age, last_name, first_name, age_group, person] = vars("age", "last name", "first name", @@ -1226,245 +1095,219 @@ group_by(age, [last_name, first_name], age_group) ``` ## true - -**WOQL.true() ⇒ `WOQLQuery`** - +##### WOQL.true() ⇒ WOQLQuery A function that always matches, always returns true -**Returns**: `WOQLQuery` - A WOQLQuery object containing the true value that will match any pattern\ -**Example** - +**Returns**: WOQLQuery - A WOQLQuery object containing the true value that will match any pattern +**Example** ```javascript when(true()).triple("a", "b", "c") ``` ## path - -**WOQL.path(subject, pattern, object, \[resultVarName]) ⇒ `WOQLQuery`** - +##### WOQL.path(subject, pattern, object, [resultVarName]) ⇒ WOQLQuery Performs a path regular expression match on the graph -**Returns**: `WOQLQuery` - - A WOQLQuery which contains the path regular expression matching expression - -| Param | Type | Description | -| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| subject | `string` \| `Var` | An IRI or variable that refers to an IRI representing the subject, i.e. the starting point of the path | -| pattern | `string` | (string) - A path regular expression describing a pattern through multiple edges of the graph (see: https://terminusdb.com/docs/index/terminusx-db/how-to-guides/path-queries) | -| object | `string` \| `Var` | An IRI or variable that refers to an IRI representing the object, i.e. ending point of the path | -| \[resultVarName] | `string` \| `Var` | A variable in which the actual paths traversed will be stored | +**Returns**: WOQLQuery - - A WOQLQuery which contains the path regular expression matching expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | An IRI or variable that refers to an IRI representing the subject, i.e. the starting point of the path | +| pattern | string | (string) - A path regular expression describing a pattern through multiple edges of the graph (see: https://terminusdb.com/docs/index/terminusx-db/how-to-guides/path-queries) | +| object | string \| Var | An IRI or variable that refers to an IRI representing the object, i.e. ending point of the path | +| [resultVarName] | string \| Var | A variable in which the actual paths traversed will be stored | +**Example** ```javascript let [person, grand_uncle, lineage] = vars("person", "grand uncle", "lineage") path(person, "((father|mother) {2,2}), brother)", grand_uncle, lineage) ``` ## size - -**WOQL.size(resourceId, resultVarName)** - +##### WOQL.size(resourceId, resultVarName) Calculates the size in bytes of the contents of the resource identified in ResourceID -| Param | Type | Description | -| ------------- | ----------------- | ---------------------------------------------------------------------------------- | -| resourceId | `string` \| `Var` | A valid resource identifier string (can refer to any graph / branch / commit / db) | -| resultVarName | `string` \| `Var` | The variable name | -**Example** +| Param | Type | Description | +| --- | --- | --- | +| resourceId | string \| Var | A valid resource identifier string (can refer to any graph / branch / commit / db) | +| resultVarName | string \| Var | The variable name | +**Example** ```javascript let [varSize] = vars("varSize") size("admin/minecraft/local/branch/main/instance/main", varSize) //returns the number of bytes in the main instance graph on the main branch ``` -## triple\_count - -**WOQL.triple\_count(resourceId, tripleCount) ⇒ `WOQLQuery`** - +## triple_count +##### WOQL.triple\_count(resourceId, tripleCount) ⇒ WOQLQuery Calculates the number of triples of the contents of the resource identified in ResourceID -**Returns**: `WOQLQuery` - A WOQLQuery which contains the size expression - -| Param | Type | Description | -| ----------- | ----------------------------- | ---------------------------------------------------------------------------------- | -| resourceId | `string` \| `Var` | A valid resource identifier string (can refer to any graph / branch / commit / db) | -| tripleCount | `string` \| `number` \| `Var` | An integer literal with the size in bytes or a variable containing that integer | +**Returns**: WOQLQuery - A WOQLQuery which contains the size expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| resourceId | string \| Var | A valid resource identifier string (can refer to any graph / branch / commit / db) | +| tripleCount | string \| number \| Var | An integer literal with the size in bytes or a variable containing that integer | +**Example** ```javascript let [count] = vars("count") triple_count("admin/minecraft/local/_commits", count) //returns the number of bytes in the local commit graph ``` -## type\_of - -**WOQL.type\_of(elementId, elementType) ⇒ `WOQLQuery`** - +## type_of +##### WOQL.type\_of(elementId, elementType) ⇒ WOQLQuery Returns true if 'elementId' is of type 'elementType', according to the current DB schema -**Returns**: `WOQLQuery` - A WOQLQuery object containing the type\_of pattern matching rule - -| Param | Type | Description | -| ----------- | ----------------- | -------------------------------- | -| elementId | `string` \| `Var` | the id of a schema graph element | -| elementType | `string` \| `Var` | the element type | - -## star +**Returns**: WOQLQuery - A WOQLQuery object containing the type_of pattern matching rule -**WOQL.star(\[graph], \[subject], \[predicate], \[object]) ⇒ `WOQLQuery`** +| Param | Type | Description | +| --- | --- | --- | +| elementId | string \| Var | the id of a schema graph element | +| elementType | string \| Var | the element type | -Generates a query that by default matches all triples in a graph identified by "graph" or in all the current terminusDB's graph -**Returns**: `WOQLQuery` - A WOQLQuery which contains the pattern matching expression +## star +##### WOQL.star([graph], [subject], [predicate], [object]) ⇒ WOQLQuery +Generates a query that by default matches all triples in a graph identified by "graph" +or in all the current terminusDB's graph -| Param | Type | Description | -| ------------ | --------------------- | -------------------------------------------------------------------------------------------- | -| \[graph] | `string` \| `boolean` | false or the resource identifier of a graph possible value are schema/{main - myschema - \*} | -| \[subject] | `string` \| `Var` | The IRI of a triple’s subject or a variable, default value "v:Subject" | -| \[predicate] | `string` \| `Var` | The IRI of a property or a variable, default value "v:Predicate" | -| \[object] | `string` \| `Var` | The IRI of a node or a variable, or a literal, default value "v:Object" | +**Returns**: WOQLQuery - A WOQLQuery which contains the pattern matching expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [graph] | string \| boolean | false or the resource identifier of a graph possible value are schema/{main - myschema - *} | instance/{main - myschema - *} | inference/{main - myschema - *} | +| [subject] | string \| Var | The IRI of a triple’s subject or a variable, default value "v:Subject" | +| [predicate] | string \| Var | The IRI of a property or a variable, default value "v:Predicate" | +| [object] | string \| Var | The IRI of a node or a variable, or a literal, default value "v:Object" | +**Example** ```javascript star("schema/main") //will return every triple in schema/main graph ``` ## all +##### WOQL.all([subject], [predicate], [object], [graphRef]) ⇒ WOQLQuery +Generates a query that by default matches all triples in a graph - identical to +star() except for order of arguments -**WOQL.all(\[subject], \[predicate], \[object], \[graphRef]) ⇒ `WOQLQuery`** +**Returns**: WOQLQuery - - A WOQLQuery which contains the pattern matching expression +all("mydoc") +//will return every triple in the instance/main graph that has "doc:mydoc" as its subject -Generates a query that by default matches all triples in a graph - identical to star() except for order of arguments +| Param | Type | Description | +| --- | --- | --- | +| [subject] | string \| Var | The IRI of a triple’s subject or a variable | +| [predicate] | string \| Var | The IRI of a property or a variable | +| [object] | string \| Var | The IRI of a node or a variable, or a literal | +| [graphRef] | typedef.GraphRef | the resource identifier of a graph possible value are schema/{main - myschema - *} | instance/{main - myschema - *} | inference/{main - myschema - *} | -**Returns**: `WOQLQuery` - - A WOQLQuery which contains the pattern matching expression all("mydoc") //will return every triple in the instance/main graph that has "doc:mydoc" as its subject - -| Param | Type | Description | -| ------------ | ------------------ | ----------------------------------------------------------------------------------- | -| \[subject] | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| \[predicate] | `string` \| `Var` | The IRI of a property or a variable | -| \[object] | `string` \| `Var` | The IRI of a node or a variable, or a literal | -| \[graphRef] | `typedef.GraphRef` | the resource identifier of a graph possible value are schema/{main - myschema - \*} | ## node +##### WOQL.node(nodeid, [chainType]) ⇒ WOQLQuery +Specifies the identity of a node that can then be used in subsequent builder functions. +Note that node() requires subsequent chained functions to complete the triples / quads +that it produces - by itself it only generates the subject. -**WOQL.node(nodeid, \[chainType]) ⇒ `WOQLQuery`** - -Specifies the identity of a node that can then be used in subsequent builder functions. Note that node() requires subsequent chained functions to complete the triples / quads that it produces - by itself it only generates the subject. +**Returns**: WOQLQuery - - A WOQLQuery which contains the partial Node pattern matching expression -**Returns**: `WOQLQuery` - - A WOQLQuery which contains the partial Node pattern matching expression - -| Param | Type | Description | -| ------------ | --------------------- | ---------------------------------------------------------------------------------------------------- | -| nodeid | `string` \| `Var` | The IRI of a node or a variable containing an IRI which will be the subject of the builder functions | -| \[chainType] | `typedef.FuntionType` | Optional type of builder function to build (default is triple) | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| nodeid | string \| Var | The IRI of a node or a variable containing an IRI which will be the subject of the builder functions | +| [chainType] | typedef.FuntionType | Optional type of builder function to build (default is triple) | +**Example** ```javascript node("mydoc").label("my label") //equivalent to triple("mydoc", "label", "my label") ``` ## insert +##### WOQL.insert(classId, classType, [graphRef]) ⇒ WOQLQuery +Inserts a single triple into the database declaring the Node to have type Type, +optionally into the specified graph -**WOQL.insert(classId, classType, \[graphRef]) ⇒ `WOQLQuery`** - -Inserts a single triple into the database declaring the Node to have type Type, optionally into the specified graph - -**Returns**: `WOQLQuery` - A WOQLQuery which contains the insert expression +**Returns**: WOQLQuery - A WOQLQuery which contains the insert expression -| Param | Type | Description | -| ----------- | ------------------ | --------------------------------------------------------------------------------------- | -| classId | `string` \| `Var` | IRI string or variable containing the IRI of the node to be inserted | -| classType | `string` \| `Var` | IRI string or variable containing the IRI of the type of the node (class/document name) | -| \[graphRef] | `typedef.GraphRef` | Optional Graph resource identifier | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| classId | string \| Var | IRI string or variable containing the IRI of the node to be inserted | +| classType | string \| Var | IRI string or variable containing the IRI of the type of the node (class/document name) | +| [graphRef] | typedef.GraphRef | Optional Graph resource identifier | +**Example** ```javascript insert("mydoc", "MyType") //equivalent to add_triple("mydoc", "rdf:type", "@schema:MyType") ``` ## graph - -**WOQL.graph(\[graphRef]) ⇒ `WOQLQuery`** - +##### WOQL.graph([graphRef]) ⇒ WOQLQuery Sets the graph resource ID that will be used for subsequent chained function calls -**Returns**: `WOQLQuery` - A WOQLQuery which contains the partial Graph pattern matching expression +**Returns**: WOQLQuery - A WOQLQuery which contains the partial Graph pattern matching expression -| Param | Type | Description | -| ----------- | ------------------ | -------------------------------------------------------------------------------------------- | -| \[graphRef] | `typedef.GraphRef` | Resource String identifying the graph which will be used for subsequent chained schema calls | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [graphRef] | typedef.GraphRef | Resource String identifying the graph which will be used for subsequent chained schema calls | +**Example** ```javascript WOQL.graph("schema") //equivalent to add_quad("MyClass", "label", "My Class Label", "schema/main") ``` ## nuke - -**WOQL.nuke(\[graphRef]) ⇒ `WOQLQuery`** - +##### WOQL.nuke([graphRef]) ⇒ WOQLQuery Deletes all triples in the passed graph (defaults to instance/main) -**Returns**: `WOQLQuery` - - A WOQLQuery which contains the deletion expression - -| Param | Type | Description | -| ----------- | ------------------ | ---------------------------------------------------------------------------- | -| \[graphRef] | `typedef.GraphRef` | Resource String identifying the graph from which all triples will be removed | +**Returns**: WOQLQuery - - A WOQLQuery which contains the deletion expression -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [graphRef] | typedef.GraphRef | Resource String identifying the graph from which all triples will be removed | +**Example** ```javascript nuke("schema/main") //will delete everything from the schema/main graph ``` ## query - -**WOQL.query() ⇒ `WOQLQuery`** - +##### WOQL.query() ⇒ WOQLQuery Generates an empty WOQLQuery object -**Example** - +**Example** ```javascript let q = query() //then q.triple(1, 1) ... ``` ## json +##### WOQL.json([JSON_LD]) ⇒ WOQLQuery \| object +Generates a WOQLQuery object from the passed WOQL JSON - if an argument is passed, +the query object is created from it, if none is passed, the current state is +returned as a JSON-LD -**WOQL.json(\[JSON\_LD]) ⇒ `WOQLQuery` | `object`** - -Generates a WOQLQuery object from the passed WOQL JSON - if an argument is passed, the query object is created from it, if none is passed, the current state is returned as a JSON-LD +**Returns**: WOQLQuery \| object - either a JSON-LD or a WOQLQuery object -**Returns**: `WOQLQuery` | `object` - either a JSON-LD or a WOQLQuery object +json version of query for passing to api -json version of query for passing to api +| Param | Type | Description | +| --- | --- | --- | +| [JSON_LD] | object | JSON-LD woql document encoding a query | -| Param | Type | Description | -| ----------- | -------- | -------------------------------------- | -| \[JSON\_LD] | `object` | JSON-LD woql document encoding a query | ## lib +##### WOQL.lib() ⇒ WOQLQuery +get the predefined library query [WOQLLibrary](/api/woqlLibrary.js?id=WOQLLibrary) -**WOQL.lib() ⇒ `WOQLQuery`** - -get the predefined library query [WOQLLibrary](../../../api/woqlLibrary.js) - -**Returns**: `WOQLQuery` - WOQLQuery object\ -**Example** - +**Returns**: WOQLQuery - WOQLQuery object +**Example** ```javascript //get commits older than the specified commit id const query = WOQL.lib().previousCommits('m8vpxewh2aovfauebfkbzwmj4qwr5lb') @@ -1481,253 +1324,231 @@ const query = WOQL.lib().branches() ``` ## string - -**WOQL.string(val) ⇒ `object`** - +##### WOQL.string(val) ⇒ object Generates explicitly a JSON-LD string literal from the input -**Returns**: `object` - - A JSON-LD string literal - -| Param | Type | Description | -| ----- | --------------------------------- | -------------------------- | -| val | `string` \| `boolean` \| `number` | any primitive literal type | +**Returns**: object - - A JSON-LD string literal -**Example** +| Param | Type | Description | +| --- | --- | --- | +| val | string \| boolean \| number | any primitive literal type | +**Example** ```javascript string(1) //returns { "@type": "xsd:string", "@value": "1" } ``` ## literal - -**WOQL.literal(val, type) ⇒ `object`** - +##### WOQL.literal(val, type) ⇒ object Generates explicitly a JSON-LD string literal from the input -**Returns**: `object` - - A JSON-LD literal - -| Param | Type | Description | -| ----- | -------- | ------------------ | -| val | `string` | any literal type | -| type | `string` | an xsd or xdd type | +**Returns**: object - - A JSON-LD literal -**Example** +| Param | Type | Description | +| --- | --- | --- | +| val | string | any literal type | +| type | string | an xsd or xdd type | +**Example** ```javascript literal(1, "nonNegativeInteger") //returns { "@type": "xsd:nonNegativeInteger", "@value": 1 } ``` ## date - -**WOQL.date(date) ⇒ `object`** - +##### WOQL.date(date) ⇒ object Generates explicitly a JSON-LD literal date from the imput -**Returns**: `object` - - A JSON-LD literal date +**Returns**: object - - A JSON-LD literal date -| Param | Type | Description | -| ----- | -------- | ----------------------------------- | -| date | `string` | any date format string (YYYY-MM-DD) | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| date | string | any date format string (YYYY-MM-DD) | +**Example** ```javascript date("2022-10-02") //returns { "@type": "xsd:date", "@value": "2022-10-02" } ``` ## datetime - -**WOQL.datetime(datetime) ⇒ `object`** - +##### WOQL.datetime(datetime) ⇒ object Generates explicitly a JSON-LD literal datetime from the imput -**Returns**: `object` - - A JSON-LD literal datetime - -| Param | Type | Description | -| -------- | -------- | ------------------------------------------------- | -| datetime | `string` | any datetime format string (YYYY-MM-DDThh-mm-ssZ) | +**Returns**: object - - A JSON-LD literal datetime -**Example** +| Param | Type | Description | +| --- | --- | --- | +| datetime | string | any datetime format string (YYYY-MM-DDThh-mm-ssZ) | +**Example** ```javascript datetime("2022-10-19T14:17:12Z") //returns { "@type": "xsd:dateTime", "@value": "2022-10-19T14:17:12Z" } ``` ## boolean - -**WOQL.boolean(bool) ⇒ `object`** - +##### WOQL.boolean(bool) ⇒ object Generates explicitly a JSON-LD literal boolean from the input -**Returns**: `object` - - A JSON-LD literal boolean +**Returns**: object - - A JSON-LD literal boolean -| Param | Type | Description | -| ----- | --------- | ----------- | -| bool | `boolean` | true | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| bool | boolean | true | false | +**Example** ```javascript boolean(true) //returns { "@type": "xsd:boolean", "@value": true } ``` ## iri - -**WOQL.iri(val) ⇒ `object`** - +##### WOQL.iri(val) ⇒ object Explicitly sets a value to be an IRI - avoiding automatic type marshalling -**Returns**: `object` - - A JSON-LD IRI value - -| Param | Type | Description | -| ----- | -------- | -------------------------------------- | -| val | `string` | string which will be treated as an IRI | +**Returns**: object - - A JSON-LD IRI value -## vars +| Param | Type | Description | +| --- | --- | --- | +| val | string | string which will be treated as an IRI | -**WOQL.vars(...varNames) ⇒ `array.`** +## vars +##### WOQL.vars(...varNames) ⇒ array.<Var> Generates javascript variables for use as WOQL variables within a query -**Returns**: `array.` - an array of javascript variables which can be dereferenced using the array destructuring operation - -| Param | Type | -| ----------- | -------- | -| ...varNames | `string` | +**Returns**: array.<Var> - an array of javascript variables which can be dereferenced using the +array destructuring operation -**Example** +| Param | Type | +| --- | --- | +| ...varNames | string | +**Example** ```javascript const [a, b, c] = WOQL.vars("a", "b", "c") //a, b, c are javascript variables which can be used as WOQL variables in subsequent queries ``` ## doc +##### WOQL.doc(object) ⇒ object +Produces an encoded form of a document that can be used by a WOQL operation +such as `WOQL.insert_document`. -**WOQL.doc(object) ⇒ `object`** - -Produces an encoded form of a document that can be used by a WOQL operation such as `WOQL.insert_document`. - -**Returns**: `object` - The encoded document +**Returns**: object - The encoded document -| Param | Type | Description | -| ------ | -------- | ------------------ | -| object | `object` | Document to encode | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| object | object | Document to encode | +**Example** ```javascript const doc = WOQL.doc({ "@type": "Person", name: "Newperson" }) ``` ## client +##### ~~WOQL.client(client) ⇒ WOQLClient~~ +***Deprecated*** -**WOQL.client(client) ⇒ `WOQLClient`** - -Gets/Sets woqlClient +Use instead to run your query woqlclient.query('myWOQLQuery') -| Param | Type | -| ------ | ------------ | -| client | `WOQLClient` | -## Vars +| Param | Type | +| --- | --- | +| client | WOQLClient | -**WOQL.Vars(...varNames) ⇒ `object.`** -| Param | Type | -| ----------- | -------- | -| ...varNames | `string` | +## Vars +##### WOQL.Vars(...varNames) ⇒ object.<Var> -**Example** +| Param | Type | +| --- | --- | +| ...varNames | string | +**Example** ```javascript const v = WOQL.Vars('var01', 'var02', 'var03'); triple(v.var01, v.var02, v.var03) ``` ## emerge +##### WOQL.emerge(auto_eval) +query module +allow you to use WOQL words as top level functions -**WOQL.emerge(auto\_eval)** -query module allow you to use WOQL words as top level functions +| Param | Type | +| --- | --- | +| auto_eval | \* | -| Param | Type | -| ---------- | ---- | -| auto\_eval | `*` | -## update\_triple +## update_triple +##### WOQL.update\_triple(subject, predicate, newObjValue, oldObjValue) ⇒ WOQLQuery +Update a pattern matching rule for the triple (Subject, Predicate, oldObjValue) with the +new one (Subject, Predicate, newObjValue) -**WOQL.update\_triple(subject, predicate, newObjValue, oldObjValue) ⇒ `WOQLQuery`** +**Returns**: WOQLQuery - A WOQLQuery which contains the a Update Triple Statement -Update a pattern matching rule for the triple (Subject, Predicate, oldObjValue) with the new one (Subject, Predicate, newObjValue) +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| newObjValue | string \| Var | The value to update or a literal | +| oldObjValue | string \| Var | The old value of the object | -**Returns**: `WOQLQuery` - A WOQLQuery which contains the a Update Triple Statement -| Param | Type | Description | -| ----------- | ----------------- | ------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| newObjValue | `string` \| `Var` | The value to update or a literal | -| oldObjValue | `string` \| `Var` | The old value of the object | +## update_quad +##### WOQL.update\_quad(subject, predicate, newObject, graphRef) ⇒ WOQLQuery +Update a pattern matching rule for the quad [S, P, O, G] (Subject, Predicate, Object, Graph) -## update\_quad +**Returns**: WOQLQuery - A WOQLQuery which contains the a Update Quad Statement -**WOQL.update\_quad(subject, predicate, newObject, graphRef) ⇒ `WOQLQuery`** +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| newObject | string \| Var | The value to update or a literal | +| graphRef | typedef.GraphRef | A valid graph resource identifier string | -Update a pattern matching rule for the quad \[S, P, O, G] (Subject, Predicate, Object, Graph) - -**Returns**: `WOQLQuery` - A WOQLQuery which contains the a Update Quad Statement - -| Param | Type | Description | -| --------- | ------------------ | ------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| newObject | `string` \| `Var` | The value to update or a literal | -| graphRef | `typedef.GraphRef` | A valid graph resource identifier string | ## value +##### WOQL.value(subject, predicate, objValue) ⇒ WOQLQuery +Creates a pattern matching rule for a triple [Subject, Predicate, Object] +add extra information about the type of the value object -**WOQL.value(subject, predicate, objValue) ⇒ `WOQLQuery`** +**Returns**: WOQLQuery - A WOQLQuery which contains the a quad or a triple Statement -Creates a pattern matching rule for a triple \[Subject, Predicate, Object] add extra information about the type of the value object +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| objValue | string \| number \| boolean \| Var | an specific value | -**Returns**: `WOQLQuery` - A WOQLQuery which contains the a quad or a triple Statement - -| Param | Type | Description | -| --------- | ------------------------------------------ | ------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| objValue | `string` \| `number` \| `boolean` \| `Var` | an specific value | ## link +##### WOQL.link(subject, predicate, object) ⇒ WOQLQuery +Creates a pattern matching rule for a triple [Subject, Predicate, Object] -**WOQL.link(subject, predicate, object) ⇒ `WOQLQuery`** - -Creates a pattern matching rule for a triple \[Subject, Predicate, Object] +**Returns**: WOQLQuery - A WOQLQuery which contains the a quad or a triple Statement -**Returns**: `WOQLQuery` - A WOQLQuery which contains the a quad or a triple Statement +| Param | Type | Description | +| --- | --- | --- | +| subject | string \| Var | The IRI of a triple’s subject or a variable | +| predicate | string \| Var | The IRI of a property or a variable | +| object | string \| Var | The IRI of a node or a variable, or a literal | -| Param | Type | Description | -| --------- | ----------------- | --------------------------------------------- | -| subject | `string` \| `Var` | The IRI of a triple’s subject or a variable | -| predicate | `string` \| `Var` | The IRI of a property or a variable | -| object | `string` \| `Var` | The IRI of a node or a variable, or a literal | ## dot - -**WOQL.dot(document, field, value) ⇒ `WOQLQuery`** - +##### WOQL.dot(document, field, value) ⇒ WOQLQuery Extract the value of a key in a bound document. -**Returns**: `WOQLQuery` - A WOQLQuery which contains the a dot Statement +**Returns**: WOQLQuery - A WOQLQuery which contains the a dot Statement + +| Param | Type | Description | +| --- | --- | --- | +| document | string \| Var | Document which is being accessed. | +| field | string \| Var | The field from which the document which is being accessed. | +| value | string \| Var | The value for the document and field. | -| Param | Type | Description | -| -------- | ----------------- | ---------------------------------------------------------- | -| document | `string` \| `Var` | Document which is being accessed. | -| field | `string` \| `Var` | The field from which the document which is being accessed. | -| value | `string` \| `Var` | The value for the document and field. | diff --git a/guides/reference-guides/javascript-client-reference/woqlclient.md b/guides/reference-guides/javascript-client-reference/woqlclient.md index 18adc90b..16d830d3 100644 --- a/guides/reference-guides/javascript-client-reference/woqlclient.md +++ b/guides/reference-guides/javascript-client-reference/woqlclient.md @@ -1,20 +1,24 @@ -# WOQLClient +# WOQLClient ## WOQLClient +The core functionality of the TerminusDB javascript client is +defined in the WOQLClient class - in the woqlClient.js file. This class provides +methods which allow you to directly get and set all of the configuration and API +endpoints of the client. The other parts of the WOQL core - connectionConfig.js +and connectionCapabilities.js - are used by the client to store internal state - they +should never have to be accessed directly. For situations where you want to communicate +with a TerminusDB server API, the WOQLClient class is all you will need. -The core functionality of the TerminusDB javascript client is defined in the WOQLClient class - in the woqlClient.js file. This class provides methods which allow you to directly get and set all of the configuration and API endpoints of the client. The other parts of the WOQL core - connectionConfig.js and connectionCapabilities.js - are used by the client to store internal state - they should never have to be accessed directly. For situations where you want to communicate with a TerminusDB server API, the WOQLClient class is all you will need. - -**License**: Apache Version 2 - -## new WOQLClient(serverUrl, \[params]) +**License**: Apache Version 2 -| Param | Type | Description | -| --------- | ------------------- | ---------------------------------------- | -| serverUrl | `string` | the terminusdb server url | -| \[params] | `typedef.ParamsObj` | an object with the connection parameters | +## new WOQLClient(serverUrl, [params]) -**Example** +| Param | Type | Description | +| --- | --- | --- | +| serverUrl | string | the terminusdb server url | +| [params] | typedef.ParamsObj | an object with the connection parameters | +**Example** ```javascript //to connect with your local terminusDB const client = new TerminusClient.WOQLClient(SERVER_URL,{user:"admin",key:"myKey"}) @@ -26,7 +30,7 @@ async function getSchema() { //The client has an internal state which defines what //organization / database / repository / branch / ref it is currently attached to -//to connect with your TerminusCMS Cloud Instance +//to connect with your TerminusDB Cloud Instance const client = new TerminusClient.WOQLClient('SERVER_CLOUD_URL/mycloudTeam', {user:"myemail@something.com", organization:'mycloudTeam'}) @@ -48,179 +52,160 @@ async function getSchema() { ## TerminusDB Client API ## Connect +##### ~~woqlClient.connect([params]) ⇒ Promise~~ +***Deprecated*** -~~**woqlClient.connect(\[params]) ⇒**** ****`Promise`**~~ +You can call this to get the server info or override the start params +configuration, this.connectionConfig.server will be used if present, +or the promise will be rejected. -_**Deprecated**_ +**Returns**: Promise - the connection capabilities response object or an error object -Connect to a Terminus server at the given URI with an API key Stores the system:ServerCapability document returned in the connection register which stores, the url, key, capabilities, and database meta-data for the connected server this.connectionConfig.server will be used if present, or the promise will be rejected. - -**Returns**: `Promise` - the connection capabilities response object or an error object - -| Param | Type | Description | -| --------- | ------------------- | --------------------------------------- | -| \[params] | `typedef.ParamsObj` | TerminusDB Server connection parameters | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [params] | typedef.ParamsObj | TerminusDB Server connection parameters | +**Example** ```javascript client.connect() ``` ## Create Database - -**woqlClient.createDatabase(dbId, dbDetails, \[orgId]) ⇒ `Promise`** - +##### woqlClient.createDatabase(dbId, dbDetails, [orgId]) ⇒ Promise Creates a new database in TerminusDB server -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| --------- | ------------------- | -------------------------------------------------------------------------- | -| dbId | `string` | The id of the new database to be created | -| dbDetails | `typedef.DbDetails` | object containing details about the database to be created | -| \[orgId] | `string` | optional organization id - if absent default local organization id is used | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| dbId | string | The id of the new database to be created | +| dbDetails | typedef.DbDetails | object containing details about the database to be created | +| [orgId] | string | optional organization id - if absent default local organization id is used | +**Example** ```javascript //remember set schema:true if you need to add a schema graph client.createDatabase("mydb", {label: "My Database", comment: "Testing", schema: true}) ``` ## Delete Database - -**woqlClient.deleteDatabase(dbId, \[orgId], \[force]) ⇒ `Promise`** - +##### woqlClient.deleteDatabase(dbId, [orgId], [force]) ⇒ Promise Deletes a database from a TerminusDB server -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| -------- | --------- | ------------------------------------------------------------------------------------------------------ | -| dbId | `string` | The id of the database to be deleted | -| \[orgId] | `string` | the id of the organization to which the database belongs (in desktop use, this will always be “admin”) | -| \[force] | `boolean` | | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| dbId | string | The id of the database to be deleted | +| [orgId] | string | the id of the organization to which the database belongs (in desktop use, this will always be “admin”) | +| [force] | boolean | | +**Example** ```javascript client.deleteDatabase("mydb") ``` ## Get Triples +##### woqlClient.getTriples(graphType) ⇒ Promise +Retrieve the contents of a graph within a TerminusDB as triples, encoded in +the turtle (ttl) format -**woqlClient.getTriples(graphType) ⇒ `Promise`** - -Retrieve the contents of a graph within a TerminusDB as triples, encoded in the turtle (ttl) format - -**Returns**: `Promise` - A promise that returns the call response object (with the contents being a string representing a set of triples in turtle (ttl) format), or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object (with +the contents being a string representing a set of triples in turtle (ttl) format), +or an Error if rejected. -| Param | Type | Description | -| --------- | ------------------- | ---------------------------------------------------------------- | -| graphType | `typedef.GraphType` | type of graph to get triples from, either “instance” or “schema” | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| graphType | typedef.GraphType | type of graph to get triples from, either “instance” or “schema” | +**Example** ```javascript const turtle = await client.getTriples("schema", "alt") ``` ## Update Triples +##### woqlClient.updateTriples(graphType, turtle, commitMsg) ⇒ Promise +Replace the contents of the specified graph with the passed triples encoded +in the turtle (ttl) format -**woqlClient.updateTriples(graphType, turtle, commitMsg) ⇒ `Promise`** - -Replace the contents of the specified graph with the passed triples encoded in the turtle (ttl) format - -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| --------- | -------- | ---------------------------------------------------- | -| graphType | `string` | type of graph | -| turtle | `string` | string encoding triples in turtle (ttl) format | -| commitMsg | `string` | Textual message describing the reason for the update | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| graphType | string | type of graph |instance|schema|inference| | +| turtle | string | string encoding triples in turtle (ttl) format | +| commitMsg | string | Textual message describing the reason for the update | +**Example** ```javascript client.updateTriples("schema", "alt", turtle_string, "dumping triples to graph alt") ``` ## Query - -**woqlClient.query(woql, \[commitMsg], \[allWitnesses], \[lastDataVersion], \[getDataVersion]) ⇒ `Promise`** - +##### woqlClient.query(woql, [commitMsg], [allWitnesses], [lastDataVersion], [getDataVersion]) ⇒ Promise Executes a WOQL query on the specified database and returns the results -**Returns**: `Promise` - A promise that returns the call response object or object having _result_ and _dataVersion_ object if _**getDataVersion**_ parameter is true, or an Error if rejected. - -| Param | Type | Description | -| ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| woql | `WOQLQuery` | an instance of the WOQLQuery class | -| \[commitMsg] | `string` | a message describing the reason for the change that will be written into the commit log (only relevant if the query contains an update) | -| \[allWitnesses] | `boolean` | | -| \[lastDataVersion] | `string` | the last data version tracking id. | -| \[getDataVersion] | `boolean` | If true the function will return object having result and dataVersion. | +**Returns**: Promise - A promise that returns the call response object or object having *result* +and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| woql | WOQLQuery | an instance of the WOQLQuery class | +| [commitMsg] | string | a message describing the reason for the change that will be written into the commit log (only relevant if the query contains an update) | +| [allWitnesses] | boolean | | +| [lastDataVersion] | string | the last data version tracking id. | +| [getDataVersion] | boolean | If true the function will return object having result and dataVersion. | +**Example** ```javascript const result = await client.query(WOQL.star()) ``` ## Clonedb - -**woqlClient.clonedb(cloneSource, newDbId, \[orgId]) ⇒ `Promise`** - +##### woqlClient.clonedb(cloneSource, newDbId, [orgId]) ⇒ Promise Clones a remote repo and creates a local copy -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ----------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| cloneSource | `typedef.CloneSourceDetails` | object describing the source branch to be used as a base | -| newDbId | `string` | id of the new cloned database on the local server | -| \[orgId] | `string` | id of the local organization that the new cloned database will be created in (in desktop mode this is always “admin”) | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| cloneSource | typedef.CloneSourceDetails | object describing the source branch to be used as a base | +| newDbId | string | id of the new cloned database on the local server | +| [orgId] | string | id of the local organization that the new cloned database will be created in (in desktop mode this is always “admin”) | +**Example** ```javascript client.clonedb({remote_url: "https://my.terminusdb.com/myorg/mydb", label "Cloned DB", comment: "Cloned from mydb"}, newid: "mydb") ``` ## Branch +##### woqlClient.branch(newBranchId, [isEmpty]) ⇒ Promise +Creates a new branch with a TerminusDB database, starting from the current context of +the client (branch / ref) -**woqlClient.branch(newBranchId, \[isEmpty]) ⇒ `Promise`** - -Creates a new branch with a TerminusDB database, starting from the current context of the client (branch / ref) +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ----------- | --------- | ------------------------------------------------------------------------- | -| newBranchId | `string` | local identifier of the new branch the ID of the new branch to be created | -| \[isEmpty] | `boolean` | if isEmpty is true it will create a empty branch. | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| newBranchId | string | local identifier of the new branch the ID of the new branch to be created | +| [isEmpty] | boolean | if isEmpty is true it will create a empty branch. | +**Example** ```javascript client.branch("dev") ``` ## Rebase - -**woqlClient.rebase(rebaseSource) ⇒ `Promise`** - +##### woqlClient.rebase(rebaseSource) ⇒ Promise Merges the passed branch into the current one using the rebase operation -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ------------ | -------- | ------------------------------------------------------ | -| rebaseSource | `object` | json describing the source branch to be used as a base | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| rebaseSource | object | json describing the source branch to be used as a base | +**Example** ```javascript //from the branch head client.rebase({rebase_from: "admin/db_name/local/branch/branch_name", message: @@ -231,152 +216,139 @@ message: "Merging from dev") ``` ## Pull - -**woqlClient.pull(remoteSourceRepo) ⇒ `Promise`** - +##### woqlClient.pull(remoteSourceRepo) ⇒ Promise Pull changes from a branch on a remote database to a branch on a local database -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ---------------- | --------------------------- | ------------------------------------------- | -| remoteSourceRepo | `typedef.RemoteRepoDetails` | an object describing the source of the pull | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| remoteSourceRepo | typedef.RemoteRepoDetails | an object describing the source of the pull | +**Example** ```javascript client.pull({remote: "origin", remote_branch: "main", message: "Pulling from remote"}) ``` ## Push - -**woqlClient.push(remoteTargetRepo) ⇒ `Promise`** - +##### woqlClient.push(remoteTargetRepo) ⇒ Promise Push changes from a branch on a local database to a branch on a remote database -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ---------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| remoteTargetRepo | `typedef.RemoteRepoDetails` | an object describing the target of the push {remote: "origin", "remote\_branch": "main", "author": "admin", "message": "message"} | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| remoteTargetRepo | typedef.RemoteRepoDetails | an object describing the target of the push {remote: "origin", "remote_branch": "main", "author": "admin", "message": "message"} | +**Example** ```javascript client.push({remote: "origin", remote_branch: "main", message: "Pulling from remote"}) ``` ## Fetch - -**woqlClient.fetch(remoteId) ⇒ `Promise`** - +##### woqlClient.fetch(remoteId) ⇒ Promise Fetch updates to a remote database to a remote repository with the local database -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| -------- | -------- | ---------------------------------------- | -| remoteId | `string` | if of the remote to fetch (eg: 'origin') | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -## local\_auth +| Param | Type | Description | +| --- | --- | --- | +| remoteId | string | if of the remote to fetch (eg: 'origin') | -~~**woqlClient.local\_auth**~~ -_**Deprecated**_ +## local_auth +##### ~~woqlClient.local\_auth~~ +***Deprecated*** -Use [#localAuth](woqlclient.md#localAuth) instead. +Use [#localAuth](#localAuth) instead. -## remote\_auth -~~**woqlClient.remote\_auth**~~ +## remote_auth +##### ~~woqlClient.remote\_auth~~ +***Deprecated*** -_**Deprecated**_ +Use [#remoteAuth](#remoteAuth) instead. -Use [#remoteAuth](woqlclient.md#remoteAuth) instead. ## setApiKey - -**woqlClient.setApiKey(accessToken)** - +##### woqlClient.setApiKey(accessToken) set the api key to access the cloud resources -| Param | Type | -| ----------- | -------- | -| accessToken | `string` | -## customHeaders +| Param | Type | +| --- | --- | +| accessToken | string | -**woqlClient.customHeaders(customHeaders) ⇒ `object`** +## customHeaders +##### woqlClient.customHeaders(customHeaders) ⇒ object add extra headers to your request -| Param | Type | -| ------------- | -------- | -| customHeaders | `object` | - -## copy - -**woqlClient.copy() ⇒** [**`WOQLClient`**](woqlclient.md#WOQLClient) -creates a copy of the client with identical internal state and context useful if we want to change context for a particular API call without changing the current client context +| Param | Type | +| --- | --- | +| customHeaders | object | -**Returns**: [`WOQLClient`](woqlclient.md#WOQLClient) - new client object with identical state to original but which can be manipulated independently\ -**Example** +## copy +##### woqlClient.copy() ⇒ [WOQLClient](#WOQLClient) +creates a copy of the client with identical internal state and context +useful if we want to change context for a particular API call without changing +the current client context + +**Returns**: [WOQLClient](#WOQLClient) - new client object with identical state to original but +which can be manipulated independently +**Example** ```javascript let newClient = client.copy() ``` ## server +##### woqlClient.server() ⇒ string +Gets the current connected server url +it can only be set creating a new WOQLCLient instance -**woqlClient.server() ⇒ `string`** - -Gets the current connected server url it can only be set creating a new WOQLCLient instance ## api - -**woqlClient.api() ⇒ `string`** - +##### woqlClient.api() ⇒ string Retrieve the URL of the server’s API base that we are currently connected to -**Returns**: `string` - the URL of the TerminusDB server api endpoint we are connected to (typically server() + “api/”)\ -**Example** - +**Returns**: string - the URL of the TerminusDB server api endpoint we are connected +to (typically server() + “api/”) +**Example** ```javascript let api_url = client.api() ``` ## organization +##### woqlClient.organization([orgId]) ⇒ string \| boolean +Gets/Sets the client’s internal organization context value, if you change the organization +name the databases list will be set to empty -**woqlClient.organization(\[orgId]) ⇒ `string` | `boolean`** - -Gets/Sets the client’s internal organization context value, if you change the organization name the databases list will be set to empty - -| Param | Type | Description | -| -------- | --------------------- | ----------------------------------------- | -| \[orgId] | `string` \| `boolean` | the organization id to set the context to | -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [orgId] | string \| boolean | the organization id to set the context to | +**Example** ```javascript client.organization("admin") ``` ## hasDatabase - -**woqlClient.hasDatabase(\[orgName], \[dbName]) ⇒ `Promise`** - +##### woqlClient.hasDatabase([orgName], [dbName]) ⇒ Promise Checks if a database exists -Returns true if a DB exists and false if it doesn't. Other results throw an exception. +Returns true if a DB exists and false if it doesn't. Other results +throw an exception. -| Param | Type | Description | -| ---------- | -------- | ----------------------------------------- | -| \[orgName] | `string` | the organization id to set the context to | -| \[dbName] | `string` | the db name to set the context to | -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [orgName] | string | the organization id to set the context to | +| [dbName] | string | the db name to set the context to | +**Example** ```javascript async function executeIfDatabaseExists(f){ const hasDB = await client.hasDatabase("admin", "testdb") @@ -387,15 +359,12 @@ async function executeIfDatabaseExists(f){ ``` ## getDatabases - -**woqlClient.getDatabases() ⇒ `Promise`** - +##### woqlClient.getDatabases() ⇒ Promise Gets the organization's databases list. If no organization has been set up, the function throws an exception -**Example** - +**Example** ```javascript async function callGetDatabases(){ const dbList = await client.getDatabases() @@ -404,19 +373,17 @@ async function callGetDatabases(){ ``` ## databases +##### woqlClient.databases([dbList]) ⇒ array +Set/Get the organization's databases list (id, label, comment) that the current +user has access to on the server. -**woqlClient.databases(\[dbList]) ⇒ `array`** - -Set/Get the organization's databases list (id, label, comment) that the current user has access to on the server. - -**Returns**: `array` - the organization's databases list +**Returns**: array - the organization's databases list -| Param | Type | Description | -| --------- | ------- | ---------------------------------------------------------------------- | -| \[dbList] | `array` | a list of databases the user has access to on the server, each having: | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [dbList] | array | a list of databases the user has access to on the server, each having: | +**Example** ```javascript //to get the list of all organization's databases async function callGetDatabases(){ @@ -426,157 +393,136 @@ async function callGetDatabases(){ ``` ## user +##### woqlClient.user() ⇒ Object +Gets the current user object as returned by the connect capabilities response +user has fields: [id, name, notes, author] -**woqlClient.user() ⇒ `Object`** - -Gets the current user object as returned by the connect capabilities response user has fields: \[id, name, notes, author] ## userOrganization - -**woqlClient.userOrganization() ⇒ `string`** - -**Returns**: `string` - the user organization name\ -**Desription**: Gets the user's organization id +##### woqlClient.userOrganization() ⇒ string +**Returns**: string - the user organization name +**Desription**: Gets the user's organization id ## databaseInfo - -**woqlClient.databaseInfo(\[dbName]) ⇒ `object`** - +##### woqlClient.databaseInfo([dbName]) ⇒ object Gets the database's details -**Returns**: `object` - the database description object +**Returns**: object - the database description object -| Param | Type | Description | -| --------- | -------- | ---------------- | -| \[dbName] | `string` | the datbase name | - -## db +| Param | Type | Description | +| --- | --- | --- | +| [dbName] | string | the datbase name | -**woqlClient.db(\[dbId]) ⇒ `string` | `boolean`** +## db +##### woqlClient.db([dbId]) ⇒ string \| boolean Sets / Gets the current database -**Returns**: `string` | `boolean` - - the current database or false - -| Param | Type | Description | -| ------- | -------- | ------------------------------------- | -| \[dbId] | `string` | the database id to set the context to | +**Returns**: string \| boolean - - the current database or false -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [dbId] | string | the database id to set the context to | +**Example** ```javascript client.db("mydb") ``` ## setSystemDb - -**woqlClient.setSystemDb()** - +##### woqlClient.setSystemDb() Sets the internal client context to allow it to talk to the server’s internal system database -## repo - -**woqlClient.repo(\[repoId]) ⇒ `string`** +## repo +##### woqlClient.repo([repoId]) ⇒ string Gets / Sets the client’s internal repository context value (defaults to ‘local’) -**Returns**: `string` - the current repository id within the client context +**Returns**: string - the current repository id within the client context -| Param | Type | Description | -| --------- | ------------------------------ | ---------------------- | -| \[repoId] | `typedef.RepoType` \| `string` | default value is local | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [repoId] | typedef.RepoType \| string | default value is local | +**Example** ```javascript client.repo("origin") ``` ## checkout - -**woqlClient.checkout(\[branchId]) ⇒ `string`** - +##### woqlClient.checkout([branchId]) ⇒ string Gets/Sets the client’s internal branch context value (defaults to ‘main’) -**Returns**: `string` - the current branch id within the client context +**Returns**: string - the current branch id within the client context -| Param | Type | Description | -| ----------- | -------- | ----------------------------------- | -| \[branchId] | `string` | the branch id to set the context to | +| Param | Type | Description | +| --- | --- | --- | +| [branchId] | string | the branch id to set the context to | -## ref - -**woqlClient.ref(\[commitId]) ⇒ `string` | `boolean`** -Sets / gets the current ref pointer (pointer to a commit within a branch) Reference ID or Commit ID are unique hashes that are created whenever a new commit is recorded - -**Returns**: `string` | `boolean` - the current commit id within the client context +## ref +##### woqlClient.ref([commitId]) ⇒ string \| boolean +Sets / gets the current ref pointer (pointer to a commit within a branch) +Reference ID or Commit ID are unique hashes that are created whenever a new commit is recorded -| Param | Type | Description | -| ----------- | -------- | ----------------------------- | -| \[commitId] | `string` | the reference ID or commit ID | +**Returns**: string \| boolean - the current commit id within the client context -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [commitId] | string | the reference ID or commit ID | +**Example** ```javascript client.ref("mkz98k2h3j8cqjwi3wxxzuyn7cr6cw7") ``` ## localAuth - -**woqlClient.localAuth(\[newCredential]) ⇒ `typedef.CredentialObj` | `boolean`** - +##### woqlClient.localAuth([newCredential]) ⇒ typedef.CredentialObj \| boolean Sets/Gets set the database basic connection credential -| Param | Type | -| ---------------- | ----------------------- | -| \[newCredential] | `typedef.CredentialObj` | -**Example** +| Param | Type | +| --- | --- | +| [newCredential] | typedef.CredentialObj | +**Example** ```javascript client.localAuth({user:"admin","key":"mykey","type":"basic"}) ``` ## remoteAuth +##### woqlClient.remoteAuth([newCredential]) ⇒ typedef.CredentialObj \| boolean +Sets/Gets the jwt token for authentication +we need this to connect 2 terminusdb server to each other for push, pull, clone actions -**woqlClient.remoteAuth(\[newCredential]) ⇒ `typedef.CredentialObj` | `boolean`** - -Sets/Gets the jwt token for authentication we need this to connect 2 terminusdb server to each other for push, pull, clone actions -| Param | Type | -| ---------------- | ----------------------- | -| \[newCredential] | `typedef.CredentialObj` | - -**Example** +| Param | Type | +| --- | --- | +| [newCredential] | typedef.CredentialObj | +**Example** ```javascript client.remoteAuth({"key":"dhfmnmjglkrelgkptohkn","type":"jwt"}) ``` ## author - -**woqlClient.author() ⇒ `string`** - +##### woqlClient.author() ⇒ string Gets the string that will be written into the commit log for the current user -**Returns**: `string` - the current user\ -**Example** - +**Returns**: string - the current user +**Example** ```javascript client.author() ``` ## set +##### woqlClient.set(params) -**woqlClient.set(params)** - -| Param | Type | Description | -| ------ | ------------------- | ------------------------------- | -| params | `typedef.ParamsObj` | a object with connection params | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| params | typedef.ParamsObj | a object with connection params | +**Example** ```javascript sets several of the internal state values in a single call (similar to connect, but only sets internal client state, does not communicate with server) @@ -584,224 +530,206 @@ client.set({key: "mypass", branch: "dev", repo: "origin"}) ``` ## resource +##### woqlClient.resource(resourceType, [resourceId]) ⇒ string +Generates a resource string for the required context +of the current context for "commits" "meta" "branch" and "ref" special resources -**woqlClient.resource(resourceType, \[resourceId]) ⇒ `string`** - -Generates a resource string for the required context of the current context for "commits" "meta" "branch" and "ref" special resources +**Returns**: string - a resource string for the desired context -**Returns**: `string` - a resource string for the desired context - -| Param | Type | Description | -| ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------ | -| resourceType | `typedef.ResourceType` | the type of resource string that is required - one of “db”, “meta”, “repo”, “commits”, “branch”, “ref” | -| \[resourceId] | `string` | can be used to specify a specific branch / ref - if not supplied the current context will be used | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| resourceType | typedef.ResourceType | the type of resource string that is required - one of “db”, “meta”, “repo”, “commits”, “branch”, “ref” | +| [resourceId] | string | can be used to specify a specific branch / ref - if not supplied the current context will be used | +**Example** ```javascript const branch_resource = client.resource("branch") ``` ## updateDatabase - -**woqlClient.updateDatabase(dbDoc) ⇒ `Promise`** - +##### woqlClient.updateDatabase(dbDoc) ⇒ Promise Update a database in TerminusDB server -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ----- | --------------- | ---------------------------------------------------------- | -| dbDoc | `typedef.DbDoc` | object containing details about the database to be updated | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| dbDoc | typedef.DbDoc | object containing details about the database to be updated | +**Example** ```javascript client.updateDatabase({id: "mydb", label: "My Database", comment: "Testing"}) ``` ## insertTriples - -**woqlClient.insertTriples(graphType, turtle, commitMsg) ⇒ `Promise`** - +##### woqlClient.insertTriples(graphType, turtle, commitMsg) ⇒ Promise Appends the passed turtle to the contents of a graph -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| --------- | -------- | ---------------------------------------------------- | -| graphType | `string` | type of graph | -| turtle | `string` | is a valid set of triples in turtle format (OWL) | -| commitMsg | `string` | Textual message describing the reason for the update | +| Param | Type | Description | +| --- | --- | --- | +| graphType | string | type of graph |instance|schema|inference| | +| turtle | string | is a valid set of triples in turtle format (OWL) | +| commitMsg | string | Textual message describing the reason for the update | -## message - -**woqlClient.message(message, \[pathname]) ⇒ `Promise`** +## message +##### woqlClient.message(message, [pathname]) ⇒ Promise Sends a message to the server -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ----------- | -------- | ------------------------------------ | -| message | `string` | textual string | -| \[pathname] | `string` | a server path to send the message to | +| Param | Type | Description | +| --- | --- | --- | +| message | string | textual string | +| [pathname] | string | a server path to send the message to | -## action - -**woqlClient.action(actionName, \[payload]) ⇒ `Promise`** +## action +##### woqlClient.action(actionName, [payload]) ⇒ Promise Sends an action to the server -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ---------- | -------- | ----------------------- | -| actionName | `string` | structure of the action | -| \[payload] | `object` | a request body call | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -## info +| Param | Type | Description | +| --- | --- | --- | +| actionName | string | structure of the action | +| [payload] | object | a request body call | -**woqlClient.info() ⇒ `Promise`** +## info +##### woqlClient.info() ⇒ Promise Gets TerminusDB Server Information -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected.\ -**Example** - +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. +**Example** ```javascript client.info() ``` ## squashBranch - -**woqlClient.squashBranch(branchId, commitMsg) ⇒ `Promise`** - +##### woqlClient.squashBranch(branchId, commitMsg) ⇒ Promise Squash branch commits -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| --------- | -------- | ---------------------------------------------------- | -| branchId | `string` | local identifier of the new branch | -| commitMsg | `string` | Textual message describing the reason for the update | +| Param | Type | Description | +| --- | --- | --- | +| branchId | string | local identifier of the new branch | +| commitMsg | string | Textual message describing the reason for the update | -## resetBranch -**woqlClient.resetBranch(branchId, commitId) ⇒ `Promise`** +## resetBranch +##### woqlClient.resetBranch(branchId, commitId) ⇒ Promise +Reset branch to a commit id, Reference ID or Commit ID are unique hashes that are +created whenever a new commit is recorded -Reset branch to a commit id, Reference ID or Commit ID are unique hashes that are created whenever a new commit is recorded +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +| Param | Type | Description | +| --- | --- | --- | +| branchId | string | local identifier of the new branch | +| commitId | string | Reference ID or Commit ID | -| Param | Type | Description | -| -------- | -------- | ---------------------------------- | -| branchId | `string` | local identifier of the new branch | -| commitId | `string` | Reference ID or Commit ID | ## optimizeBranch - -**woqlClient.optimizeBranch(branchId) ⇒ `Promise`** - +##### woqlClient.optimizeBranch(branchId) ⇒ Promise Optimize db branch -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| -------- | -------- | ---------------------------------- | -| branchId | `string` | local identifier of the new branch | - -## deleteBranch +| Param | Type | Description | +| --- | --- | --- | +| branchId | string | local identifier of the new branch | -**woqlClient.deleteBranch(branchId) ⇒ `Promise`** +## deleteBranch +##### woqlClient.deleteBranch(branchId) ⇒ Promise Deletes a branch from database -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| -------- | -------- | ------------------------------ | -| branchId | `string` | local identifier of the branch | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -## reset +| Param | Type | Description | +| --- | --- | --- | +| branchId | string | local identifier of the branch | -**woqlClient.reset(commitPath) ⇒ `Promise`** +## reset +##### woqlClient.reset(commitPath) ⇒ Promise Reset the current branch HEAD to the specified commit path -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ---------- | -------- | -------------------------------------------- | -| commitPath | `string` | The commit path to set the current branch to | +| Param | Type | Description | +| --- | --- | --- | +| commitPath | string | The commit path to set the current branch to | -## dispatch - -**woqlClient.dispatch() ⇒ `Promise`** +## dispatch +##### woqlClient.dispatch() ⇒ Promise Common request dispatch function -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected.\ +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. **Properties** -| Name | Type | Description | -| ----------------- | --------- | ---------------------------------------------------------- | -| action | `string` | the action name | -| apiUrl | `string` | the server call endpoint | -| \[payload] | `object` | the post body | -| \[getDataVersion] | `boolean` | If true return response with data version | -| \[compress] | `boolean` | If true, compress the data if it is bigger than 1024 bytes | +| Name | Type | Description | +| --- | --- | --- | +| action | string | the action name | +| apiUrl | string | the server call endpoint | +| [payload] | object | the post body | +| [getDataVersion] | boolean | If true return response with data version | +| [compress] | boolean | If true, compress the data if it is bigger than 1024 bytes | -## generateCommitInfo - -**woqlClient.generateCommitInfo(msg, \[author]) ⇒ `object`** +## generateCommitInfo +##### woqlClient.generateCommitInfo(msg, [author]) ⇒ object Generates the json structure for commit messages -| Param | Type | Description | -| --------- | -------- | ------------------------------------------------------------------ | -| msg | `string` | textual string describing reason for the change | -| \[author] | `string` | optional author id string - if absent current user id will be used | -## generateCommitDescriptor +| Param | Type | Description | +| --- | --- | --- | +| msg | string | textual string describing reason for the change | +| [author] | string | optional author id string - if absent current user id will be used | -**woqlClient.generateCommitDescriptor(commitId)** +## generateCommitDescriptor +##### woqlClient.generateCommitDescriptor(commitId) Generates the json structure for commit descriptor -| Param | Type | Description | -| -------- | -------- | ------------------- | -| commitId | `string` | a valid commit id o | -## prepareRevisionControlArgs +| Param | Type | Description | +| --- | --- | --- | +| commitId | string | a valid commit id o | -**woqlClient.prepareRevisionControlArgs(\[rc\_args]) ⇒ `object` | `boolean`** +## prepareRevisionControlArgs +##### woqlClient.prepareRevisionControlArgs([rc_args]) ⇒ object \| boolean Adds an author string (from the user object returned by connect) to the commit message. -| Param | Type | -| ----------- | -------- | -| \[rc\_args] | `object` | -## addDocument +| Param | Type | +| --- | --- | +| [rc_args] | object | -**woqlClient.addDocument(json, \[params], \[dbId], \[string], \[lastDataVersion], \[getDataVersion]) ⇒ `Promise`** +## addDocument +##### woqlClient.addDocument(json, [params], [dbId], [string], [lastDataVersion], [getDataVersion]) ⇒ Promise to add a new document or a list of new documents into the instance or the schema graph. -**Returns**: `Promise` - A promise that returns the call response object or object having _result_ and _dataVersion_ object if _**getDataVersion**_ parameter is true, or an Error if rejected. - -| Param | Type | Description | -| ------------------ | ----------------------- | --------------------------------------------------------------------------------- | -| json | `object` | | -| \[params] | `typedef.DocParamsPost` | the post parameters [#typedef.DocParamsPost](woqlclient.md#typedef.DocParamsPost) | -| \[dbId] | `string` | the dbid | -| \[string] | `message` | the insert commit message | -| \[lastDataVersion] | `string` | the last data version tracking id. | -| \[getDataVersion] | `boolean` | If true the function will return object having result and dataVersion. | +**Returns**: Promise - A promise that returns the call response object or object having *result* +and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| json | object | | +| [params] | typedef.DocParamsPost | the post parameters [#typedef.DocParamsPost](#typedef.DocParamsPost) | +| [dbId] | string | the dbid | +| [string] | message | the insert commit message | +| [lastDataVersion] | string | the last data version tracking id. | +| [getDataVersion] | boolean | If true the function will return object having result and dataVersion. | +**Example** ```javascript const json = [{ "@type" : "Class", "@id" : "Coordinate", @@ -816,8 +744,28 @@ const json = [{ "@type" : "Class", "name" : "xsd:string", "perimeter" : { "@type" : "List", "@class" : "Coordinate" } }] -client.addDocument(json,{"graph_type":"schema"},"mydb","add new schema") +client.addDocument(json,{"graph_type":"schema"},"mydb","add new schema documents") + +//if we would like to override the entire schema +const json = [ +{"@base": "terminusdb:///data/", + "@schema": "terminusdb:///schema#", + "@type": "@context" + }, + { + "@id": "Person", + "@key": { + "@type": "Random" + }, + "@type": "Class", + "name": { + "@class": "xsd:string", + "@type": "Optional" + } + }] +// client.addDocument(json,{"graph_type":"schema","full_replace:true"}, + "mydb","update the all schema"); // Here we will pass true to show how to get dataVersion @@ -844,26 +792,24 @@ const response1 = await client.addDocument(json, {"graph_type": "schema"}, ``` ## queryDocument +##### ~~woqlClient.queryDocument(query, [params], [dbId], [branch], [lastDataVersion], [getDataVersion]) ⇒ Promise~~ +***Deprecated*** -~~**woqlClient.queryDocument(query, \[params], \[dbId], \[branch], \[lastDataVersion], \[getDataVersion]) ⇒**** ****`Promise`**~~ +Use [#getDocument](#getDocument) instead. -_**Deprecated**_ +**Returns**: Promise - A promise that returns the call response object or object having *result* +and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected. -Use [#getDocument](woqlclient.md#getDocument) instead. - -**Returns**: `Promise` - A promise that returns the call response object or object having _result_ and _dataVersion_ object if _**getDataVersion**_ parameter is true, or an Error if rejected. - -| Param | Type | Description | -| ------------------ | ---------------------- | ---------------------------------------------------------------------- | -| query | `object` | the query template | -| \[params] | `typedef.DocParamsGet` | the get parameters | -| \[dbId] | `string` | the database id | -| \[branch] | `string` | the database branch | -| \[lastDataVersion] | `string` | the last data version tracking id. | -| \[getDataVersion] | `boolean` | If true the function will return object having result and dataVersion. | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| query | object | the query template | +| [params] | typedef.DocParamsGet | the get parameters | +| [dbId] | string | the database id | +| [branch] | string | the database branch | +| [lastDataVersion] | string | the last data version tracking id. | +| [getDataVersion] | boolean | If true the function will return object having result and dataVersion. | +**Example** ```javascript const query = { "type": "Person", @@ -908,22 +854,20 @@ console.log(response); ``` ## getDocument - -**woqlClient.getDocument(\[params], \[dbId], \[branch], \[lastDataVersion], \[getDataVersion], \[query]) ⇒ `Promise`** - -**Returns**: `Promise` - A promise that returns the call response object or object having _result_ and _dataVersion_ object if _**getDataVersion**_ parameter is true, or an Error if rejected. - -| Param | Type | Description | -| ------------------ | ---------------------- | ------------------------------------------------------------------------------- | -| \[params] | `typedef.DocParamsGet` | the get parameters, you can pass document query search template with the params | -| \[dbId] | `string` | the database id | -| \[branch] | `string` | the database branch | -| \[lastDataVersion] | `string` | the last data version tracking id. | -| \[getDataVersion] | `boolean` | If true the function will return object having result and dataVersion. | -| \[query] | `object` | document query search template | - -**Example** - +##### woqlClient.getDocument([params], [dbId], [branch], [lastDataVersion], [getDataVersion], [query]) ⇒ Promise +**Returns**: Promise - A promise that returns the call response object or object having *result* +and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected. + +| Param | Type | Description | +| --- | --- | --- | +| [params] | typedef.DocParamsGet | the get parameters, you can pass document query search template with the params | +| [dbId] | string | the database id | +| [branch] | string | the database branch | +| [lastDataVersion] | string | the last data version tracking id. | +| [getDataVersion] | boolean | If true the function will return object having result and dataVersion. | +| [query] | object | document query search template | + +**Example** ```javascript //return the schema graph as a json array client.getDocument({"graph_type":"schema","as_list":true}).then(result={ @@ -936,8 +880,8 @@ client.getDocument({"graph_type":"schema","as_list":true,"id":"Country"}).then(r }) //pass a document query template to query the document interface -const queryTemplate = { "name": "Ireland", "@type":"Country" } -client.getDocument({"graph_type":"schema","as_list":true, +const queryTemplate = { "name": "Ireland"} +client.getDocument({"as_list":true, "@type":"Country" query:queryTemplate}).then(result=>{ console.log(result) }) @@ -969,23 +913,22 @@ const response1 = await client.getDocument({"graph_type":"schema","as_list":true ``` ## updateDocument - -**woqlClient.updateDocument(json, \[params], \[dbId], \[message], \[lastDataVersion], \[getDataVersion], \[create]) ⇒ `Promise`** - -**Returns**: `Promise` - A promise that returns the call response object or object having _result_ and _dataVersion_ object if _**getDataVersion**_ parameter is true, or an Error if rejected. - -| Param | Type | Description | -| ------------------ | ---------------------- | ------------------------------------------------------------------------------ | -| json | `object` | | -| \[params] | `typedef.DocParamsPut` | the Put parameters [#typedef.DocParamsPut](woqlclient.md#typedef.DocParamsPut) | -| \[dbId] | `*` | the database id | -| \[message] | `*` | the update commit message | -| \[lastDataVersion] | `string` | the last data version tracking id. | -| \[getDataVersion] | `boolean` | If true the function will return object having result and dataVersion. | -| \[create] | `boolean` | If true, the function will create a new document if it doesn't exist. | - -**Example** - +##### woqlClient.updateDocument(json, [params], [dbId], [message], [lastDataVersion], [getDataVersion], [compress], [create]) ⇒ Promise +**Returns**: Promise - A promise that returns the call response object or object having *result* +and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected. + +| Param | Type | Description | +| --- | --- | --- | +| json | object | | +| [params] | typedef.DocParamsPut | the Put parameters [#typedef.DocParamsPut](#typedef.DocParamsPut) | +| [dbId] | \* | the database id | +| [message] | \* | the update commit message | +| [lastDataVersion] | string | the last data version tracking id. | +| [getDataVersion] | boolean | If true the function will return object having result and dataVersion. | +| [compress] | boolean | If true, the function will create a new document if it doesn't exist. | +| [create] | boolean | Perform an *upsert* which inserts if the document is not present (also works on nested documents) | + +**Example** ```javascript client.updateDocument( { @@ -1042,26 +985,35 @@ const response1 = await client.updateDocument( "", response.dataVersion ); + + // update a document and create the linked document together + // we are update the document "Person/Person01" + // and create a new document {"@type": "Person","name": "child01"} at the same time + const response1 = await client.updateDocument( + { + "@id": "Person/Person01", + "@type": "Person", + "name": "Person01" + "children":[{"@type": "Person","name": "child01"}] + },{create:true}) ``` ## deleteDocument - -**woqlClient.deleteDocument(\[params], \[dbId], \[message], \[lastDataVersion], \[getDataVersion]) ⇒ `Promise`** - +##### woqlClient.deleteDocument([params], [dbId], [message], [lastDataVersion], [getDataVersion]) ⇒ Promise to delete the document -**Returns**: `Promise` - A promise that returns the call response object or object having _result_ and _dataVersion_ object if _**getDataVersion**_ parameter is true, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object or object having *result* +and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected. -| Param | Type | Description | -| ------------------ | ------------------------- | ---------------------------------------------------------------------- | -| \[params] | `typedef.DocParamsDelete` | | -| \[dbId] | `string` | the database id | -| \[message] | `string` | the delete message | -| \[lastDataVersion] | `string` | the last data version tracking id. | -| \[getDataVersion] | `boolean` | If true the function will return object having result and dataVersion. | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [params] | typedef.DocParamsDelete | | +| [dbId] | string | the database id | +| [message] | string | the delete message | +| [lastDataVersion] | string | the last data version tracking id. | +| [getDataVersion] | boolean | If true the function will return object having result and dataVersion. | +**Example** ```javascript client.deleteDocument({"graph_type":"schema",id:['Country','Coordinate']}) @@ -1094,147 +1046,124 @@ const response1 = await client.deleteDocument({"graph_type":"schema", ``` ## getSchemaFrame - -**woqlClient.getSchemaFrame(\[type], \[dbId]) ⇒ `Promise`** - +##### woqlClient.getSchemaFrame([type], [dbId]) ⇒ Promise The purpose of this method is to quickly discover the supported fields of a particular type. -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ------- | -------- | -------------------------------------------------------------------------------------------- | -| \[type] | `string` | If given, the type to get information for. If omitted, information for all types is returned | -| \[dbId] | `string` | the database id | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [type] | string | If given, the type to get information for. If omitted, information for all types is returned | +| [dbId] | string | the database id | +**Example** ```javascript client.getSchemaFrame("Country") ``` ## getSchema - -**woqlClient.getSchema(\[dbId], \[branch]) ⇒ `Promise`** - +##### woqlClient.getSchema([dbId], [branch]) ⇒ Promise get the database schema in json format -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| --------- | -------- | ---------------------------- | -| \[dbId] | `string` | the database id | -| \[branch] | `string` | specific a branch/collection | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [dbId] | string | the database id | +| [branch] | string | specific a branch/collection | +**Example** ```javascript client.getSchema() ``` ## getClasses - -**woqlClient.getClasses(\[dbId]) ⇒ `Promise`** - +##### woqlClient.getClasses([dbId]) ⇒ Promise get all the schema classes (documents,subdocuments,abstracts) -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ------- | -------- | --------------- | -| \[dbId] | `string` | the database id | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [dbId] | string | the database id | +**Example** ```javascript client.getClasses() ``` ## getEnums - -**woqlClient.getEnums(\[dbId]) ⇒ `Promise`** - +##### woqlClient.getEnums([dbId]) ⇒ Promise get all the Enum Objects -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | -| ------- | -------- | -| \[dbId] | `string` | - -**Example** +| Param | Type | +| --- | --- | +| [dbId] | string | +**Example** ```javascript client.getEnums() ``` ## getClassDocuments - -**woqlClient.getClassDocuments(\[dbId]) ⇒ `Promise`** - +##### woqlClient.getClassDocuments([dbId]) ⇒ Promise get all the Document Classes (no abstract or subdocument) -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | -| ------- | -------- | -| \[dbId] | `string` | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | +| --- | --- | +| [dbId] | string | +**Example** ```javascript client.getClassDocuments() ``` ## getBranches - -**woqlClient.getBranches(\[dbId]) ⇒ `Promise`** - +##### woqlClient.getBranches([dbId]) ⇒ Promise get the database collections list -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ------- | -------- | --------------- | -| \[dbId] | `string` | the database id | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [dbId] | string | the database id | +**Example** ```javascript client.getBranches() ``` ## getCommitsLog - -**woqlClient.getCommitsLog(\[dbId]) ⇒ `Promise`** - +##### woqlClient.getCommitsLog([start], [count]) ⇒ Promise get the database collections list -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ------- | -------- | --------------- | -| \[dbId] | `string` | the database id | - -**Example** +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [start] | number | 0 | where to start printing the commit information in the log (starting from the head of the current branch) | +| [count] | number | 1 | The number of total commit log records to return | +**Example** ```javascript -client.getCommitsLog() +client.getCommitsLog(count=10) ``` ## getPrefixes - -**woqlClient.getPrefixes(\[dbId]) ⇒ `Promise`** - +##### woqlClient.getPrefixes([dbId]) ⇒ Promise get the database prefixes object -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ------- | -------- | --------------- | -| \[dbId] | `string` | the database id | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [dbId] | string | the database id | +**Example** ```javascript client.getPrefixes() //return object example @@ -1245,14 +1174,11 @@ client.getPrefixes() ``` ## getUserOrganizations - -**woqlClient.getUserOrganizations() ⇒ `Promise`** - +##### woqlClient.getUserOrganizations() ⇒ Promise Get the list of the user's organizations and the database related -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected.\ -**Example** - +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. +**Example** ```javascript async funtion callGetUserOrganizations(){ await getUserOrganizations() @@ -1261,19 +1187,16 @@ async funtion callGetUserOrganizations(){ ``` ## userOrganizations - -**woqlClient.userOrganizations(\[orgList]) ⇒ `array`** - +##### woqlClient.userOrganizations([orgList]) ⇒ array Get/Set the list of the user's organizations (id, organization, label, comment). -**Returns**: `array` - the user Organizations list +**Returns**: array - the user Organizations list -| Param | Type | Description | -| ---------- | ------- | ----------------------------- | -| \[orgList] | `array` | a list of user's Organization | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| [orgList] | array | a list of user's Organization | +**Example** ```javascript async funtion callGetUserOrganizations(){ await client.getUserOrganizations() @@ -1281,22 +1204,94 @@ async funtion callGetUserOrganizations(){ } ``` -## getJSONDiff +## patch +##### woqlClient.patch(before, patch) ⇒ Promise +Apply a patch object to another object -**woqlClient.getJSONDiff(before, after, \[options]) ⇒ `Promise`** +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -Get the patch of difference between two documents. +| Param | Type | Description | +| --- | --- | --- | +| before | object | The current state of JSON document | +| patch | object | The patch object | + +**Example** +```javascript +client.patch( + { "@id" : "Person/Jane", "@type" : "Person", "name" : "Jane"}, + { "name" : { "@op" : "ValueSwap", "@before" : "Jane", "@after": "Janine" }} + ).then(patchResult=>{ + console.log(patchResult) +}) +//result example +//{ "@id" : "Person/Jane", "@type" : "Person", "name" : "Jannet"} +``` + +## patchResource +##### woqlClient.patchResource(patch, message) ⇒ Promise +Apply a patch object to the current resource + +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. + +| Param | Type | Description | +| --- | --- | --- | +| patch | array | The patch object | +| message | string | The commit message | + +**Example** +```javascript +const patch = [ + { + "@id": "Obj/id1", + "name": { + "@op": "SwapValue", + "@before": "foo", + "@after": "bar" + } + }, + { + "@id": "Obj/id2", + "name": { + "@op": "SwapValue", + "@before": "foo", + "@after": "bar" + } + } +] +client.db("mydb") +client.checkout("mybranch") +client.patchResource(patch,"apply patch to mybranch").then(patchResult=>{ + console.log(patchResult) +}) +// result example +// ["Obj/id1", +// "Obj/id2"] +// or conflict error 409 +// { +// "@type": "api:PatchError", +// "api:status": "api:conflict", +// "api:witnesses": [ +// { +// "@op": "InsertConflict", +// "@id_already_exists": "Person/Jane" +// } +//] +//} +``` -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +## getJSONDiff +##### woqlClient.getJSONDiff(before, after, [options]) ⇒ Promise +Get the patch of difference between two documents. -| Param | Type | Description | -| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| before | `object` | The current state of JSON document | -| after | `object` | The updated state of JSON document | -| \[options] | `object` | {keep:{\}} Options to send to the diff endpoint. The diff api outputs the changes between the input, in options you can list the properties that you would like to see in the diff result in any case. | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| before | object | The current state of JSON document | +| after | object | The updated state of JSON document | +| [options] | object | {keep:{}} Options to send to the diff endpoint. The diff api outputs the changes between the input, in options you can list the properties that you would like to see in the diff result in any case. | +**Example** ```javascript client.getJSONDiff( { "@id": "Person/Jane", "@type": "Person", name: "Jane" }, @@ -1310,22 +1305,19 @@ client.getJSONDiff( ``` ## getVersionObjectDiff - -**woqlClient.getVersionObjectDiff(dataVersion, jsonObject, id, \[options]) ⇒ `Promise`** - +##### woqlClient.getVersionObjectDiff(dataVersion, jsonObject, id, [options]) ⇒ Promise Get the patch of difference between two documents. -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| dataVersion | `string` | The version from which to compare the object | -| jsonObject | `object` | The updated state of JSON document | -| id | `string` | The document id to be diffed | -| \[options] | `object` | {keep:{\}} Options to send to the diff endpoint the diff api outputs the changes between the input, but you can list the properties that you would like to see in the diff result in any case. | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| dataVersion | string | The version from which to compare the object | +| jsonObject | object | The updated state of JSON document | +| id | string | The document id to be diffed | +| [options] | object | {keep:{}} Options to send to the diff endpoint the diff api outputs the changes between the input, but you can list the properties that you would like to see in the diff result in any case. | +**Example** ```javascript const jsonObj = { "@id": "Person/Jane", "@type": "Person", name: "Janine" } client.getVersionObjectDiff("main",jsonObj @@ -1335,22 +1327,19 @@ client.getVersionObjectDiff("main",jsonObj ``` ## getVersionDiff - -**woqlClient.getVersionDiff(beforeVersion, afterVersion, \[id], \[options]) ⇒ `Promise`** - +##### woqlClient.getVersionDiff(beforeVersion, afterVersion, [id], [options]) ⇒ Promise Get the patch of difference between branches or commits. -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -| Param | Type | Description | -| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| beforeVersion | `string` | Before branch/commit to compare | -| afterVersion | `string` | After branch/commit to compare | -| \[id] | `string` | The document id to be diffed, if it is omitted all the documents will be compared | -| \[options] | `object` | {keep:{\}} Options to send to the diff endpoint. The diff api outputs the changes between the input (branches or commits), in options you can list the properties that you would like to see in the diff result in any case. | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| beforeVersion | string | Before branch/commit to compare | +| afterVersion | string | After branch/commit to compare | +| [id] | string | The document id to be diffed, if it is omitted all the documents will be compared | +| [options] | typedef.DiffObject | {keep:{},count:10,start:0} Options to send to the diff endpoint. The diff api outputs the changes between the input (branches or commits), in options you can list the properties that you would like to see in the diff result in any case. | +**Example** ```javascript //This is to view all the changes between two commits const beforeCommit = "a73ssscfx0kke7z76083cgswszdxy6l" @@ -1371,76 +1360,70 @@ client.getVersionDiff("main", afterCommit, "Person/Tom" ).then(diffResult=>{ }) //This is to view the changes between two branches with the keep options -const options = {"keep":{"@id":true, "name": true}} +const options = {"keep":{"@id":true, "name": true}, start:0, count:10} client.getVersionDiff("main","mybranch",options).then(diffResult=>{ console.log(diffResult) }) ``` ## apply +##### woqlClient.apply(beforeVersion, afterVersion, message, [matchFinalState], [options]) +Diff two different commits and apply changes on the current branch/commit. +If you would like to change branch or commit before apply use client.checkout("branchName") -**woqlClient.apply(beforeVersion, afterVersion, message, \[matchFinalState], \[options])** - -Diff two different commits and apply changes on the current branch/commit. If you would like to change branch or commit before apply use client.checkout("branchName") -| Param | Type | Description | -| ------------------ | --------- | ------------------------------------------------ | -| beforeVersion | `string` | Before branch/commit to compare | -| afterVersion | `string` | After branch/commit to compare | -| message | `string` | apply commit message | -| \[matchFinalState] | `boolean` | the default value is false | -| \[options] | `object` | {keep:{\}} Options to send to the apply endpoint | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| beforeVersion | string | Before branch/commit to compare | +| afterVersion | string | After branch/commit to compare | +| message | string | apply commit message | +| [matchFinalState] | boolean | the default value is false | +| [options] | object | {keep:{}} Options to send to the apply endpoint | +**Example** ```javascript client.checkout("mybranch") -client.apply("main","mybranch","merge main").then(result=>{ +client.apply("mybranch","mybranch_new","merge main").then(result=>{ console.log(result) }) ``` -## patch - -**woqlClient.patch(before, patch) ⇒ `Promise`** +## getDocumentHistory +##### woqlClient.getDocumentHistory(id, [historyParams]) +Get the document's history for a specific database or branch -Patch the difference between two documents. -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ------ | -------- | ---------------------------------- | -| before | `object` | The current state of JSON document | -| patch | `object` | The patch object | - -**Example** +| Param | Type | Description | +| --- | --- | --- | +| id | string | id of document to report history of | +| [historyParams] | typedef.DocHistoryParams | | +**Example** ```javascript -let diffPatch = await client.getJSONDiff( - { "@id": "Person/Jane", "@type": "Person", name: "Jane" }, - { "@id": "Person/Jane", "@type": "Person", name: "Janine" } - ); - -let patch = await client.patch( { "@id": "Person/Jane", "@type": "Person", name: "Jane" }, -diffPatch); +//this will return the last 5 commits for the Person/Anna document +client.checkout("mybranch") +client.docHistory("Person/Anna",{start:0,count:5}).then(result=>{ + console.log(result) +}) +//this will return the last and the first commit for the Person/Anna document +client.docHistory("Person/Anna",{updated:true,created:true}).then(result=>{ + console.log(result) +}) ``` ## sendCustomRequest - -**woqlClient.sendCustomRequest(requestType, customRequestURL, \[payload]) ⇒ `Promise`** - +##### woqlClient.sendCustomRequest(requestType, customRequestURL, [payload]) ⇒ Promise Call a custom Api endpoit -**Returns**: `Promise` - A promise that returns the call response object, or an Error if rejected. - -| Param | Type | Description | -| ---------------- | -------- | ---------------------------------- | -| requestType | `string` | The current state of JSON document | -| customRequestURL | `string` | The patch object | -| \[payload] | `object` | the request payload | +**Returns**: Promise - A promise that returns the call response object, or an Error if rejected. -**Example** +| Param | Type | Description | +| --- | --- | --- | +| requestType | string | The current state of JSON document | +| customRequestURL | string | The patch object | +| [payload] | object | the request payload | +**Example** ```javascript client.sendCustomRequest("GET", "http://localhost:3030/changes/").then(result=>{ console.log(result)