Create wasm.mdx

Update wasm.mdx Update docs (#331) Fix demo script Starting merge for 0.8.0
kuzudb · prrao87 · Feb 5, 2025 · Dec 19, 2024 · Dec 19, 2024 · Dec 19, 2024
commit 227f91b2ad102c78206334c16d87fe8f2bc8a71a
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -148,6 +148,7 @@ export default defineConfig({
                         { label: 'Go', link: '/client-apis/go' },
                         { label: 'C++', link: '/client-apis/cpp' },
                         { label: 'C', link: '/client-apis/c' },
+                        { label: 'WebAssembly', link: '/client-apis/wasm' },
                         { label: '.NET', link: '/client-apis/net', badge: { text: 'Community', variant: 'caution'}},
                         { label: 'Elixir', link: '/client-apis/elixir', badge: { text: 'Community', variant: 'caution'}}
                     ],

diff --git a/src/content/docs/client-apis/wasm.mdx b/src/content/docs/client-apis/wasm.mdx
@@ -0,0 +1,146 @@
+---
+title: WebAssembly (Wasm)
+---
+
+[WebAssembly](https://webassembly.org/), a.k.a. _Wasm_, is a standard defining any suitable low-level
+programming language as compilation target, enabling deployment of software within web browsers on a variety
+of devices. This page describes Kùzu's Wasm API, enabling Kùzu databases to run inside Wasm-capable
+browsers.
+
+## Benefits of WASM
+
+Kùzu-Wasm enables the following:
+
+- Fast, in-browser graph analysis without ever sending data to a server
+- Strong data privacy guarantees, as the data never leaves the browser
+- Real-time interactive dashboards
+- Lightweight, portable solutions that leverage graphs within web applications
+
+## Installation
+
+```bash
+npm i kuzu-wasm
+```
+
+## Example usage
+
+The example shown below sets up a graph database in the browser using Kùzu's WebAssembly implementation.
+
+```js
+// Import library
+import kuzu from './index.js';
+
+(async () => {
+  // Write the data into WASM filesystem
+  const userCSV = `Adam,30
+Karissa,40
+Zhang,50
+Noura,25`;
+  const cityCSV = `Waterloo,150000
+Kitchener,200000
+Guelph,75000`;
+  const followsCSV = `Adam,Karissa,2020
+Adam,Zhang,2020
+Karissa,Zhang,2021
+Zhang,Noura,2022`;
+  const livesInCSV = `Adam,Waterloo
+Karissa,Waterloo
+Zhang,Kitchener
+Noura,Guelph`;
+
+  await kuzu.FS.writeFile("/user.csv", userCSV);
+  await kuzu.FS.writeFile("/city.csv", cityCSV);
+  await kuzu.FS.writeFile("/follows.csv", followsCSV);
+  await kuzu.FS.writeFile("/lives-in.csv", livesInCSV);
+
+  // Create an empty database and connect to it
+  const db = new kuzu.Database("./test");
+  const conn = new kuzu.Connection(db);
+
+  // Create the tables
+  await conn.query(
+    "CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name))"
+  );
+  await conn.query(
+    "CREATE NODE TABLE City(name STRING, population INT64, PRIMARY KEY (name))"
+  );
+  await conn.query("CREATE REL TABLE Follows(FROM User TO User, since INT64)");
+  await conn.query("CREATE REL TABLE LivesIn(FROM User TO City)");
+
+  // Load the data
+  await conn.query('COPY User FROM "user.csv"');
+  await conn.query('COPY City FROM "city.csv"');
+  await conn.query('COPY Follows FROM "follows.csv"');
+  await conn.query('COPY LivesIn FROM "lives-in.csv"');
+  const queryResult = await conn.query("MATCH (u:User) -[l:LivesIn]-> (c:City) RETURN u.name, c.name");
+
+  // Get all rows from the query result
+  const rows = await queryResult.getAllObjects();
+
+  // Print the rows
+  for (const row of rows) {
+    console.log(`User ${row['u.name']} lives in ${row['c.name']}`);
+  }
+})();
+```
+
+This script can be directly embedded in an HTML file, for example:
+
+```html
+<!DOCTYPE html>
+<html>
+<body>
+    <h1>Welcome to WASM Test Server</h1>
+    <script type="module">
+    // Paste the script here
+    </script>
+</body>
+</html>
+```
+
+## Understanding the package
+
+In this package, three different variants of WebAssembly modules are provided:
+- **Default**: This is the default build of the WebAssembly module. It does not support multi-threading and uses Emscripten's default filesystem. This build has the smallest size and works in both Node.js and browser environments. It has the best compatibility and does not require cross-origin isolation. However, the performance maybe limited due to the lack of multithreading support. This build is located at the root level of the package.
+- **Multi-threaded**: This build supports multi-threading and uses Emscripten's default filesystem. This build has a larger size compared to the default build and only requires [cross-origin isolation](https://web.dev/articles/cross-origin-isolation-guide) in the browser environment. This build is located in the `multithreaded` directory.
+- **Node.js**: This build is optimized for Node.js and uses Node.js's filesystem instead of Emscripten's default filesystem (`NODEFS` flag is enabled). This build also supports multi-threading. It is distributed as a CommonJS module rather than an ES module to maximize compatibility. This build is located in the `nodejs` directory. Note that this build only works in Node.js and does not work in the browser environment.
+
+In each variant, there are two different versions of the WebAssembly module:
+- **Async**: This version of the module is the default version and each function call returns a Promise. This version dispatches all the function calls to the WebAssembly module to a Web Worker or Node.js worker thread to prevent blocking the main thread. However, this version may have a slight overhead due to the serialization and deserialization of the data required by the worker threads. This version is located at the root level of each variant (e.g., `kuzu-wasm`, `kuzu-wasm/multithreaded`, `kuzu-wasm/nodejs`).
+- **Sync**: This version of the module is synchronous and does not require any callbacks (other than the module initialization). This version is good for scripting / CLI / prototyping purposes but is not recommended to be used in GUI applications or web servers because it may block the main thread and cause unexpected freezes. This alternative version is located in the `sync` directory of each variant (e.g., `kuzu-wasm/sync`, `kuzu-wasm/multithreaded/sync`, `kuzu-wasm/nodejs/sync`).
+
+Note that you cannot mix and match the variants and versions. For example, a `Database` object created with the default variant cannot be passed to a function in the multithreaded variant. Similarly, a `Database` object created with the async version cannot be passed to a function in the sync version.
+
+### Loading the Worker script (for async versions)
+In each variant, the main module is bundled as one script file. However, the worker script is located in a separate file. The worker script is required to run the WebAssembly module in a Web Worker or Node.js worker thread. If you are using a build tool like Webpack, the worker script needs to be copied to the output directory. For example, in Webpack, you can use the `copy-webpack-plugin` to copy the worker script to the output directory. 
+
+By default, the worker script is resolved under the same directory / URL prefix as the main module. If you want to change the location of the worker script, you can use pass the optional worker path parameter to the `setWorkerPath` function. For example:
+```javascript
+import { setWorkerPath } from 'kuzu-wasm';
+setWorkerPath('path/to/worker.js');
+```
+
+Note that this function must be called before any other function calls to the WebAssembly module. After the initialization is started, the worker script path cannot be changed and not finding the worker script will cause an error.
+
+For the Node.js variant, the worker script can be resolved automatically and you do not need to set the worker path.
+
+## API documentation
+The API documentation can be found [here](https://kuzudb.com/api-docs/wasm/).
+
+## Local development
+
+This section is relevant if you are interested in contributing to Kùzu's Wasm API.
+
+First, build the WebAssembly module:
+
+```bash
+npm run build
+```
+
+This will build the WebAssembly module in the `release` directory and create a tarball ready for publishing under the current directory.
+
+You can run the tests as follows:
+
+```bash
+npm test
+```
diff --git a/src/content/docs/import/copy-from-dataframe.md b/src/content/docs/import/copy-from-dataframe.md
@@ -33,7 +33,7 @@ conn.execute("COPY Person FROM df")
 
 ## Polars
 
-You can utilize an existing Polars DataFrame to copy data directly into Kùzu. 
+You can utilize an existing Polars DataFrame to copy data directly into Kùzu.
 
 ```python
 import kuzu
@@ -73,3 +73,7 @@ pa_table = pa.table({
 
 conn.execute("COPY Person FROM pa_table")
 ```
+
+## Ignore erroneous rows
+
+See the [Ignore erroneous rows](/import#ignore-erroneous-rows) section for more details.
diff --git a/src/content/docs/import/index.mdx b/src/content/docs/import/index.mdx
@@ -202,12 +202,12 @@ CALL warning_limit=1024;
 ```
 ### Skippable Errors By Source
 
-Currently `IGNORE_ERRORS` option works when scanning files (and not in-memory data frames or when running
-`COPY/LOAD FROM` on sub-queries). For different files, the errors that can be skipped can be different.
-If the error is not skippable in a file format, `COPY/LOAD FROM` will instead error and fail.
+Currently `IGNORE_ERRORS` option works when scanning files or in-memory data frames (but not when running
+`COPY/LOAD FROM` on sub-queries). For different sources, the errors that can be skipped can be different.
+If the error is not skippable for a specific source, `COPY/LOAD FROM` will instead error and fail.
 Below is a table that shows the errors that are skippable by each source.
 
 ||Parsing Errors|Casting Errors|Duplicate/Null/Missing Primary-Key errors|
 |----|----|----|----|
 |CSV| X | X | X |
-|JSON/Numpy/Parquet|||X|
+|JSON/Numpy/Parquet/PyArrow/Pandas/Polars Dataframes|||X|