doc

Author: sstalin

README.md

@@ -39,7 +39,7 @@ const conn = new Connection('mapi:monetdb://<username>:<password>@<hostname>:<po
 ## Features
 - prepared statements
 - streaming query results
-- bulk import & export with `COPY TO/COPY FROM`
+- bulk import & export with `COPY INTO`
 ## Contributing
 
 **We :heart: contributions!**

docs/pages/_meta.json

@@ -1,7 +1,9 @@
 {
   "index": "Getting Started",
+  "filetransfer": "File Transfer",
+  "result": "Query result",
+  "prepstmt": "Prepare Statement",
   "apis": "API",
-  "example": "Examples",
   "versions": {
       "title": "archive",
       "type": "menu",

docs/pages/apis/connection.mdx

@@ -24,7 +24,7 @@ const defaults = {
     password: process.env.MAPI_PASSWORD || 'monetdb',
     database: process.env.MAPI_DATABASE,
     autoCommit: false,
-    replySize: 100,
+    replySize: -1,
 };
 
 const config: MapiConfig = {

docs/pages/filetransfer.mdx

@@ -0,0 +1,43 @@
+## File Transfer
+MonetDB supports the non-standard `COPY INTO` statement to load a CSV-like
+text file into a table or to dump a table into a text file. This statement has an
+optional modifier `ON CLIENT` to indicate that the server should not
+try to open the file on the server side but instead ask the client to open it
+on its behalf.
+
+For example::
+```sql
+	COPY INTO mytable FROM 'data.csv' ON CLIENT
+	USING DELIMITERS ',', E'\n', '"';
+```
+For security reason `monetdb-nodejs` enforces files to be realtive to the current
+working directory of the Node.js process.
+## Skip rows and early cancellation
+MonetDB's `COPY INTO` statement allows you to skip, for example, the first
+line in a file using the modifier `OFFSET 2`, and load `n` records from the file using
+`RECORDS` modifier.
+```sql
+	COPY 100 RECORDS OFFSET 2 INTO mytable FROM 'data.csv' ON CLIENT
+```
+, for detailed documentation on `COPY INTO` statement please vist [MonetDB documentation](https://www.monetdb.org/documentation-Jun2023/user-guide/sql-manual/data-loading/)
+## Example
+Assume `data.csv` with the following content
+```bash
+cat<<EOF>data.csv
+1|one
+2|two
+3|three
+EOF
+```
+, then load that into MonetDB
+```ts
+import {Connection} from 'monetdb';
+
+const conn = new Connection({database: 'test'});
+const ready = await conn.connect();
+await conn.execute('create table foo(i int, a varchar(10))');
+let res = await conn.execute(`copy into foo from \'data.csv\' on client`);
+res = await conn.execute('select * from foo order by i');
+console.log(res.data);
+// [[1, 'one'], [2, 'two'], [3, 'three']]
+```

docs/pages/prepstmt.mdx

@@ -0,0 +1,13 @@
+## Prepare Statement
+The PREPARE statement compiles an SQL statement into its execution plan on the server. This is useful for statements which need to be executed many times but with different values each time, such as an INSERT or UPDATE or SELECT query.
+```ts
+const ready = await conn.connect();
+let res = await conn.execute('create table foo(a int, b boolean, c string, d date, f decimal)');
+const prepStmt = await conn.prepare('insert into foo values (?, ?, ?, ?, ?)');
+res = await prepStmt.execute(1, true, 'first', '2022-12-12', 1.11);
+res = await prepStmt.execute(2, false, 'second', '2022-12-12', 2.22);
+res = await prepStmt.execute(3, true, 'third', '2022-12-12', 3.33);
+await prepStmt.release();
+```
+For more information on prepare statement please visit [MonetDB documentation](https://www.monetdb.org/documentation-Jun2023/user-guide/sql-manual/data-manipulation/prepare-statement/). 
+

docs/pages/result.mdx

@@ -0,0 +1,41 @@
+## Query result size
+Query result size can be set with `replySize` `Connection` option. It defines the number of data rows returned in the initial response.
+By default this options is set to `-1`, which means fetch all the data. If `replySize` is set to any positive number, only that many
+data rows will be fetched, while the rest will stay cached at the server. The `replySize` can be set initially when connection is created, or by invoking `setReplySize` method on the `Connection` object.
+```ts
+// set replySize to 100
+const conn = new Connection({database: 'test', replySize: 100});
+await conn.connect();
+let res = await conn.execute("select * from generate_series(1, 1001)");
+console.log(res.data.length);
+// 100
+await conn.setReplySize(-1); // back to default
+res = await conn.execute("select * from generate_series(1, 1001)");
+console.log(res.data.length);
+// 1000
+```
+## Streaming query result
+When query result is quite large it's often useful to start process the data chunks as soon as they are available
+on the client. This can be achieved by invoking `execute` method on the `Connection` object with `stream=true`.
+```ts
+//  execute(sql: string, stream?: boolean): Promise<any>;
+const ready = await conn.connect();
+const stream: QueryStream = await conn.execute('select * from generate_series(1, 10000)', true);
+const colInfo = [];
+const data = [];
+stream.on('header', (cols: any[]) => {
+    // do something with col info
+});
+
+stream.on('data', (tuples: any[]) => {
+    for (let t of tuples) {
+        data.push(t);
+    }
+});
+
+stream.on('end', () => {
+  // do something on end of streaming
+});
+
+await conn.close();
+```