Merge pull request #16 from Linkurious/develop

1.0.2

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.0.1
+current_version = 1.0.2
 commit = False
 tag = False
 serialize =

.gitignore

@@ -3,6 +3,8 @@ sqlcl/
 **/node_modules/
 **/dist/
 example/compose-stack/transform.mjs
+example/compose-stack/transform.mjs
+example/compose-stack/dataset/*.sql
 example/**/package-lock.json
 docs/.vitepress/cache
 docs/api

.version

@@ -1 +1 @@
-1.0.1
+1.0.2

README.md

@@ -1,8 +1,8 @@
 # `@linkurious/ogma-oracle-parser`
 
-![logo](/logo.svg)
+![@linkurious/ogma-oracle-parser Logo](https://raw.githubusercontent.com/Linkurious/ogma-oracle-parser/develop/logo.svg)
 
-Seamless comunication between [Ogma](https://doc.linkurious.com/ogma/latest/) and [Oracle SQL graphs](https://docs.oracle.com/en//database/oracle/property-graph/23.3/spgdg/sql-property-graphs.html).
+Seamless comunication between [Ogma](https://doc.linkurious.com/ogma/latest/) and [Oracle Database 23ai SQL Property Graphs](https://docs.oracle.com/database/oracle/property-graph/23.4/spgdg/sql-property-graphs.html).
 
 If you don't have an Ogma licence, [contact us](https://doc.linkurious.com/ogma/latest/contact.html).
 

docs/.vitepress/config.mts

@@ -1,60 +1,64 @@
-import { DefaultTheme, defineConfig } from 'vitepress';
-import fs from 'fs/promises';
+import { DefaultTheme, defineConfig } from "vitepress";
+import fs from "fs/promises";
 
 // recursively go into input dir and create a vitepress sidebar config
 function createSidebar(dir) {
-  return fs.readdir(dir, { withFileTypes: true })
-    .then(files => {
-      const promises = files.map(file => {
+  return fs
+    .readdir(dir, { withFileTypes: true })
+    .then((files) => {
+      const promises = files.map((file) => {
         if (file.isDirectory()) {
           return createSidebar(`${dir}/${file.name}`);
-        } else if (file.name.endsWith('.md')) {
+        } else if (file.name.endsWith(".md")) {
           return {
-            text: file.name.replace('.md', ''),
-            link: `${dir.replace('docs/', '')}/${file.name.replace('.md', '')}`,
+            text: file.name.replace(".md", ""),
+            link: `${dir.replace("docs/", "")}/${file.name.replace(".md", "")}`,
           };
         }
       });
       return Promise.all(promises);
     })
-    .then(res => {
-      return res.filter(r => r);
+    .then((res) => {
+      return res.filter((r) => r);
     });
 }
-const classes = await createSidebar('docs/api/classes');
+const classes = await createSidebar("docs/api/classes");
 // const interfaces = await createSidebar('docs/api/interfaces');
 const sidebar: DefaultTheme.Sidebar = {
-  'api/': [
+  "api/": [
     {
-      text: 'OgmaOracleParser',
-      link: 'api/classes/OgmaOracleParser'
+      text: "OgmaOracleParser",
+      link: "api/classes/OgmaOracleParser",
     },
     {
-      text: 'Types',
-      link: 'api/modules'
+      text: "Types",
+      link: "api/modules",
     },
   ],
 };
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   title: "ogma-oracle-parser",
-  description: "Seamless Ogma and Oracle Property Graph integration",
-  head: [['link', { rel: 'icon', href: '/ogma-oracle-parser/favicon.ico' }]],
-  base: '/ogma-oracle-parser/',
+  description:
+    "Seamless communication between Ogma and SQL Property Graphs in the Oracle Database 23ai",
+  head: [["link", { rel: "icon", href: "/ogma-oracle-parser/favicon.ico" }]],
+  base: "/ogma-oracle-parser/",
   themeConfig: {
-    logo: '/logo-small.svg',
+    logo: "/logo-small.svg",
     nav: [
-      { text: 'Getting started', link: '/getting-started' },
-      { text: 'Example', link: '/example' },
-      { text: 'API', link: '/api/classes/OgmaOracleParser' },
-
+      { text: "Getting started", link: "/getting-started" },
+      { text: "Example", link: "/example" },
+      { text: "API", link: "/api/classes/OgmaOracleParser" },
     ],
     sidebar,
     outline: {
-      level: [2, 3]
+      level: [2, 3],
     },
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/Linkurious/ogma-oracle-graph-db' }
-    ]
-  }
+      {
+        icon: "github",
+        link: "https://github.com/Linkurious/ogma-oracle-graph-db",
+      },
+    ],
+  },
 });

docs/example.md

@@ -1,38 +1,118 @@
 # Example
 
-We provide a complete example on how to setup your graph database, connect to it, retrieve elements and display them in Ogma. And the best is that you can make it work in minutes.
+We provide a complete example on how to setup your Oracle Database as a graph database, connect to it, retrieve elements and display them in Ogma. And the best is that you can make it work in minutes.
 Let's get started:
 
 ```sh
-git clone https://github.com/Linkurious/ogma-oracle-graph-db
-cd ogma-oracle-graph-db
+git clone https://github.com/Linkurious/ogma-oracle-parser.git
+tree ogma-oracle-parser
 ```
 
 ## Setup the Database
 
-The simplest way is to use the `docker-compose` file we provide, which will:
+### Before you set up the database instance
 
-- pull the Oracle SQL server image
-- setup the users login/password
-- load a database
-- add the SQL utility functions required by the parser
+The `database` subfolder contains a curated [OpenFlights](https://openflights.org/) dataset about airports and flights connecting airports. You need to `unzip` the dataset first.
 
 ```sh
-cd example/compose-stack
-docker compose up
+cd ogma-oracle-parser/example/database
+sh ./deflate-db.sh
+ll dataset
 ```
 
-And you are done ! You know have a container exposing the port `1521` on which you can execute SQL requests.
+### Create the database container using startup scripts
 
-## Start the server
+Now, you can use `Podman` to:
+
+- pull the Oracle Database Free 23ai **full** container image from the [Oracle Container Registry](https://container-registry.oracle.com/)
+- setup the DB user login/password
+- load a sample dataset
+- create a property graph on top of the sample dataset
+
+```sh
+# Make sure you are in the right directory
+cd ~/ogma-oracle-parser/example/database
+
+# Clean up existing containers
+podman rmi --force -a
+
+# Pull a new Oracle Database 23ai Free container image
+podman run --privileged -d --name 23aifree \
+ -p 1521:1521 \
+ -e ORACLE_PWD=Welcome_1234# \
+ -e ORACLE_PDB=freepdb1 \
+ -e GRAPH_USER=graphuser \
+ -e GRAPH_PWD=Welcome_1234# \
+ -v oracle_data:/opt/oracle/oradata \
+ -v ./startup:/opt/oracle/scripts/startup \
+ -v ./dataset:/home/oracle/dataset:rw \
+ -v ./scripts:/home/oracle/scripts:rw \
+ container-registry.oracle.com/database/free:latest
+```
+
+Note: It takes about 3-4 minutes to have the container up and running. Make sure to replace the `ORACLE_PWD` and `GRAPH_PWD` passwords at a later stage.
+
+You can check the container using:
+
+```sh
+podman ps
+podman logs 23aifree
+```
+
+You now have a container running that exposes the standard Oracle Database port `1521` on which you can execute SQL requests. To test the connection to the database, do the following:
+
+```sh
+podman exec -it 23aifree sqlplus pdbadmin/Welcome_1234#@freepdb1
+```
+
+```sql
+show user
+
+select 1;
+```
+
+Logout if everything looks fine.
+
+```sql
+quit
+```
+
+As `GRAPH_USER` you can check that the property graph was created:
+
+```sh
+podman exec -it 23aifree sqlplus graphuser/Welcome_1234#@freepdb1
+```
+
+```sql
+select * from graph_table (
+   openflights_graph
+   match (a is airport)-[e]->(b is city)
+   columns (a.name as airport, a.iata as iata, b.city as city)
+)
+fetch first 10 rows only;
+```
+
+Logout if everything looks fine.
+
+```sql
+quit
+```
+
+Congratulations! You have completed the first step.
+
+## Build the Frontend
+
+Open a new SSH connection to your compute instance.
 
 ```sh
-cd example/server
+# Make sure you are in the right directory
+cd ~/ogma-oracle-parser/example/client
 ```
 
 You will need to provide your Ogma API key to be able to install Ogma via npm install.
 Either by modifying the `package.json`, either by running:
 
+
 ```sh
 npm install --save https://get.linkurio.us/api/get/npm/ogma/<VERSION>/?secret=<YOUR_API_KEY>
 ```
@@ -41,30 +121,40 @@ Then:
 
 ```sh
 npm install
-npm run start
+npm run build
 ```
+That's it! You know have a `dist` folder containing the frontend app. 
+It displays the graph. You can check the properties of nodes and edges properties by clicking on the node or edge. A double-click on a node expands it with one hop.
 
-You know have an express app that answers to a few routes by querying your SQL database:
+Now we will need to start the server in order to access it.
 
-- `[GET] /nodes/:type` Returns all nodes of a certain type. Type must match with the labels passed in your `CREATE PROPERTY GRAPH` call.
-- `[GET] /edges/:types` Returns all edges of a certain type.
-- `[GET] /node/:id` Returns the node corresponding to `id`. Id must be of the form: `LABEL-ID`.
-- `[GET] /edge/:id` Returns the edge corresponding to `id`
-- `[GET /expand/:id` Returns all the neighbors of the node refered by `id`.
+## Start the Server
 
-## Start the frontend
+```sh
+# Make sure you are in the right directory
+cd ~/ogma-oracle-parser/example/server
+```
+Same as for cient, you will need to install Ogma by providing your `API_KEY`. Then you can just proceed:
 
 ```sh
-cd example/client
+npm install --save https://get.linkurio.us/api/get/npm/ogma/<VERSION>/?secret=<YOUR_API_KEY>
 ```
 
-Same as for server, you will need to install Ogma by providing your `API_KEY`. Then you can just proceed:
+Then:
 
 ```sh
 npm install
-npm run dev
+npm run start
 ```
 
-You know have a frontend running on `http://localhost:5174/` which displays the graph, allows you to look into nodes/edges properties by clicking on it, and expand nodes by double clicking on it.
+You now have an express app that answers to a few routes by querying your SQL database:
+
+- `[GET] /nodes/:type` Returns all nodes of a certain type. Type must match with the labels passed in your `CREATE PROPERTY GRAPH` call.
+- `[GET] /edges/:types` Returns all edges of a certain type.
+- `[GET] /node/:id` Returns the node corresponding to `id`. ID must be of the form: `LABEL-ID`.
+- `[GET] /edge/:id` Returns the edge corresponding to `id`
+- `[GET /expand/:id` Returns all the neighbors of the node referred by `id`.
+
+It also serves the client app on the root route. So you can navigate to `http://localhost:1337` and see the graph displayed. Or to your remote server IP address if you are running it on a remote server.
 
 Enjoy!