flowquery 1.0.18 → 1.0.21

package/flowquery-py/misc/data/test.json

@@ -0,0 +1,10 @@
+[
+  {
+    "test": "This is a test.",
+    "description": "A simple JSON file for testing."
+  },
+  {
+    "test": "Another test entry.",
+    "description": "Another simple JSON object."
+  }
+]

package/flowquery-py/misc/data/users.json

@@ -0,0 +1,242 @@
+[
+  {
+    "id": 1,
+    "name": "Victoria Harrington",
+    "title": "Managing Partner",
+    "department": "Executive",
+    "email": "v.harrington@blackstone-legal.com",
+    "managerId": null
+  },
+  {
+    "id": 2,
+    "name": "Charles Whitmore",
+    "title": "Senior Partner",
+    "department": "Corporate Law",
+    "email": "c.whitmore@blackstone-legal.com",
+    "managerId": 1
+  },
+  {
+    "id": 3,
+    "name": "Eleanor Prescott",
+    "title": "Senior Partner",
+    "department": "Litigation",
+    "email": "e.prescott@blackstone-legal.com",
+    "managerId": 1
+  },
+  {
+    "id": 4,
+    "name": "Marcus Delgado",
+    "title": "Senior Partner",
+    "department": "Intellectual Property",
+    "email": "m.delgado@blackstone-legal.com",
+    "managerId": 1
+  },
+  {
+    "id": 5,
+    "name": "Rebecca Thornton",
+    "title": "Partner",
+    "department": "Corporate Law",
+    "email": "r.thornton@blackstone-legal.com",
+    "managerId": 2
+  },
+  {
+    "id": 6,
+    "name": "Jonathan Ashford",
+    "title": "Partner",
+    "department": "Corporate Law",
+    "email": "j.ashford@blackstone-legal.com",
+    "managerId": 2
+  },
+  {
+    "id": 7,
+    "name": "Diana Castellanos",
+    "title": "Partner",
+    "department": "Litigation",
+    "email": "d.castellanos@blackstone-legal.com",
+    "managerId": 3
+  },
+  {
+    "id": 8,
+    "name": "William Cho",
+    "title": "Partner",
+    "department": "Litigation",
+    "email": "w.cho@blackstone-legal.com",
+    "managerId": 3
+  },
+  {
+    "id": 9,
+    "name": "Natasha Okonkwo",
+    "title": "Partner",
+    "department": "Intellectual Property",
+    "email": "n.okonkwo@blackstone-legal.com",
+    "managerId": 4
+  },
+  {
+    "id": 10,
+    "name": "Samuel Brennan",
+    "title": "Senior Associate",
+    "department": "Corporate Law",
+    "email": "s.brennan@blackstone-legal.com",
+    "managerId": 5
+  },
+  {
+    "id": 11,
+    "name": "Priya Sharma",
+    "title": "Senior Associate",
+    "department": "Corporate Law",
+    "email": "p.sharma@blackstone-legal.com",
+    "managerId": 6
+  },
+  {
+    "id": 12,
+    "name": "Michael Torres",
+    "title": "Senior Associate",
+    "department": "Litigation",
+    "email": "m.torres@blackstone-legal.com",
+    "managerId": 7
+  },
+  {
+    "id": 13,
+    "name": "Katherine Webb",
+    "title": "Senior Associate",
+    "department": "Litigation",
+    "email": "k.webb@blackstone-legal.com",
+    "managerId": 8
+  },
+  {
+    "id": 14,
+    "name": "David Kim",
+    "title": "Senior Associate",
+    "department": "Intellectual Property",
+    "email": "d.kim@blackstone-legal.com",
+    "managerId": 9
+  },
+  {
+    "id": 15,
+    "name": "Lauren Mitchell",
+    "title": "Associate",
+    "department": "Corporate Law",
+    "email": "l.mitchell@blackstone-legal.com",
+    "managerId": 10
+  },
+  {
+    "id": 16,
+    "name": "Ryan Fitzgerald",
+    "title": "Associate",
+    "department": "Corporate Law",
+    "email": "r.fitzgerald@blackstone-legal.com",
+    "managerId": 10
+  },
+  {
+    "id": 17,
+    "name": "Olivia Chen",
+    "title": "Associate",
+    "department": "Corporate Law",
+    "email": "o.chen@blackstone-legal.com",
+    "managerId": 11
+  },
+  {
+    "id": 18,
+    "name": "James Patterson",
+    "title": "Associate",
+    "department": "Litigation",
+    "email": "j.patterson@blackstone-legal.com",
+    "managerId": 12
+  },
+  {
+    "id": 19,
+    "name": "Sophia Rodriguez",
+    "title": "Associate",
+    "department": "Litigation",
+    "email": "s.rodriguez@blackstone-legal.com",
+    "managerId": 13
+  },
+  {
+    "id": 20,
+    "name": "Benjamin Hayes",
+    "title": "Associate",
+    "department": "Intellectual Property",
+    "email": "b.hayes@blackstone-legal.com",
+    "managerId": 14
+  },
+  {
+    "id": 21,
+    "name": "Emily Nakamura",
+    "title": "Associate",
+    "department": "Intellectual Property",
+    "email": "e.nakamura@blackstone-legal.com",
+    "managerId": 14
+  },
+  {
+    "id": 22,
+    "name": "Thomas Grant",
+    "title": "Paralegal",
+    "department": "Corporate Law",
+    "email": "t.grant@blackstone-legal.com",
+    "managerId": 15
+  },
+  {
+    "id": 23,
+    "name": "Amanda Foster",
+    "title": "Paralegal",
+    "department": "Litigation",
+    "email": "a.foster@blackstone-legal.com",
+    "managerId": 18
+  },
+  {
+    "id": 24,
+    "name": "Daniel Reyes",
+    "title": "Paralegal",
+    "department": "Intellectual Property",
+    "email": "d.reyes@blackstone-legal.com",
+    "managerId": 20
+  },
+  {
+    "id": 25,
+    "name": "Rachel Morgan",
+    "title": "Legal Secretary",
+    "department": "Executive",
+    "email": "r.morgan@blackstone-legal.com",
+    "managerId": 1
+  },
+  {
+    "id": 26,
+    "name": "Christopher Blake",
+    "title": "Legal Secretary",
+    "department": "Corporate Law",
+    "email": "c.blake@blackstone-legal.com",
+    "managerId": 5
+  },
+  {
+    "id": 27,
+    "name": "Jessica Huang",
+    "title": "Legal Secretary",
+    "department": "Litigation",
+    "email": "j.huang@blackstone-legal.com",
+    "managerId": 7
+  },
+  {
+    "id": 28,
+    "name": "Andrew Sullivan",
+    "title": "Office Manager",
+    "department": "Operations",
+    "email": "a.sullivan@blackstone-legal.com",
+    "managerId": 1
+  },
+  {
+    "id": 29,
+    "name": "Michelle Davis",
+    "title": "Receptionist",
+    "department": "Operations",
+    "email": "m.davis@blackstone-legal.com",
+    "managerId": 28
+  },
+  {
+    "id": 30,
+    "name": "Robert Chen",
+    "title": "IT Administrator",
+    "department": "Operations",
+    "email": "r.chen@blackstone-legal.com",
+    "managerId": 28
+  }
+]

package/flowquery-py/notebooks/TestFlowQuery.ipynb

@@ -0,0 +1,440 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%reload_ext autoreload\n",
+    "%autoreload 2\n",
+    "\n",
+    "from flowquery import Runner"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "Create virtual node test"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "query: str = \"\"\"\n",
+    "    create virtual (:Fact) as {\n",
+    "        unwind range(0,6) as i\n",
+    "        load json from \"https://catfact.ninja/fact\" as item\n",
+    "        return i as id, item.fact\n",
+    "    }\n",
+    "\"\"\"\n",
+    "\n",
+    "runner: Runner = Runner(query)\n",
+    "await runner.run()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3",
+   "metadata": {},
+   "source": [
+    "Query virtual graph node"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "runner: Runner = Runner(\"match (n:Fact) return n\")\n",
+    "await runner.run()\n",
+    "for record in runner.results:\n",
+    "    print(record)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5",
+   "metadata": {},
+   "source": [
+    "Test extensibility"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from flowquery.extensibility import (\n",
+    "    Function,\n",
+    "    FunctionDef,\n",
+    "    AggregateFunction,\n",
+    "    ReducerElement,\n",
+    "    AsyncFunction,\n",
+    "    PredicateFunction\n",
+    ")\n",
+    "import aiohttp\n",
+    "import json\n",
+    "from typing import Any, List, Iterator, Union, Dict\n",
+    "\n",
+    "@FunctionDef({\n",
+    "    \"description\": \"Converts a string to uppercase\",\n",
+    "    \"category\": \"string\",\n",
+    "    \"parameters\": [\n",
+    "        {\"name\": \"text\", \"description\": \"String to convert\", \"type\": \"string\"}\n",
+    "    ],\n",
+    "    \"output\": {\"description\": \"Uppercase string\", \"type\": \"string\"}\n",
+    "})\n",
+    "class UpperCase(Function):\n",
+    "    def __init__(self):\n",
+    "        super().__init__(\"uppercase\")\n",
+    "        self._expected_parameter_count = 1\n",
+    "\n",
+    "    def value(self) -> str:\n",
+    "        return str(self.get_children()[0].value()).upper()\n",
+    "    \n",
+    "@FunctionDef({\n",
+    "    \"description\": \"Extracts nodes from a collection\",\n",
+    "    \"category\": \"scalar\",\n",
+    "    \"parameters\": [\n",
+    "        {\"name\": \"collection\", \"description\": \"Collection to extract nodes from\", \"type\": \"any[]\"}\n",
+    "    ],\n",
+    "    \"output\": {\"description\": \"List of nodes extracted from the collection\", \"type\": \"node[]\"}\n",
+    "})\n",
+    "class Nodes(Function):\n",
+    "    def __init__(self):\n",
+    "        super().__init__(\"nodes\")\n",
+    "        self._expected_parameter_count = 1\n",
+    "\n",
+    "    def value(self) -> List[Dict[str, Any]]:\n",
+    "        pattern: List[Dict[str, Any]] = self.get_children()[0].value()\n",
+    "        return list(self._nodes(pattern))\n",
+    "\n",
+    "    def _nodes(self, pattern: List[Dict[str, Any]]) -> Iterator[Dict[str, Any]]:\n",
+    "        for element in pattern:\n",
+    "            if isinstance(element, dict) and \"id\" in element:\n",
+    "                yield element\n",
+    "    \n",
+    "\n",
+    "class ProductElement(ReducerElement):\n",
+    "    def __init__(self):\n",
+    "        self._value: float = 1.0\n",
+    "\n",
+    "    @property\n",
+    "    def value(self) -> float:\n",
+    "        return self._value\n",
+    "\n",
+    "    @value.setter\n",
+    "    def value(self, v: float) -> None:\n",
+    "        self._value = v\n",
+    "    \n",
+    "@FunctionDef({\n",
+    "    \"description\": \"Calculates the product of a list of numbers\",\n",
+    "    \"category\": \"aggregate\",\n",
+    "    \"parameters\": [\n",
+    "        {\"name\": \"numbers\", \"description\": \"List of numbers to multiply\", \"type\": \"number[]\"}\n",
+    "    ],\n",
+    "    \"output\": {\"description\": \"Product of the numbers\", \"type\": \"number\"}\n",
+    "})\n",
+    "class Product(AggregateFunction):\n",
+    "    def __init__(self):\n",
+    "        super().__init__(\"product\")\n",
+    "\n",
+    "    def reduce(self, element: ReducerElement) -> None:\n",
+    "        element.value *= self.first_child().value()\n",
+    "\n",
+    "    def element(self) -> ReducerElement:\n",
+    "        return ProductElement()\n",
+    "\n",
+    "@FunctionDef({\n",
+    "    \"description\": \"Asynchronous function that fetches data from a URL\",\n",
+    "    \"category\": \"async\",\n",
+    "    \"parameters\": [\n",
+    "        {\"name\": \"url\", \"description\": \"URL to fetch data from\", \"type\": \"string\"}\n",
+    "    ],\n",
+    "    \"output\": {\"description\": \"Fetched data\", \"type\": \"string\"}\n",
+    "})\n",
+    "class get(AsyncFunction):\n",
+    "    async def generate(self, url: str):\n",
+    "        async with aiohttp.ClientSession() as session:\n",
+    "            async with session.get(url) as response:\n",
+    "                yield await response.json()\n",
+    "\n",
+    "@FunctionDef({\n",
+    "    \"description\": \"Fetch json data from a file path\",\n",
+    "    \"category\": \"async\",\n",
+    "    \"parameters\": [\n",
+    "        {\"name\": \"path\", \"description\": \"File path to fetch data from\", \"type\": \"string\"}\n",
+    "    ],\n",
+    "    \"output\": {\"description\": \"Fetched data\", \"type\": \"string\"}\n",
+    "})\n",
+    "class json_file(AsyncFunction):\n",
+    "    async def generate(self, path: str):\n",
+    "        with open(path, \"r\") as file:\n",
+    "            yield json.load(file)\n",
+    "\n",
+    "@FunctionDef({\n",
+    "    \"description\": \"Extracts values from an array with optional filtering. Uses list comprehension syntax: extract(variable IN array [WHERE condition] | expression)\",\n",
+    "    \"category\": \"predicate\",\n",
+    "    \"parameters\": [\n",
+    "        {\"name\": \"variable\", \"description\": \"Variable name to bind each element\", \"type\": \"string\"},\n",
+    "        {\"name\": \"array\", \"description\": \"Array to iterate over\", \"type\": \"array\"},\n",
+    "        {\"name\": \"expression\", \"description\": \"Expression to return for each element\", \"type\": \"any\"},\n",
+    "        {\"name\": \"where\", \"description\": \"Optional filter condition\", \"type\": \"boolean\", \"required\": False}\n",
+    "    ],\n",
+    "    \"output\": {\"description\": \"Extracted values from the array after applying the optional filter\", \"type\": \"array\", \"example\": [2, 4]},\n",
+    "    \"examples\": [\n",
+    "        \"WITH [1, 2, 3] AS nums RETURN extract(n IN nums | n)\",\n",
+    "        \"WITH [1, 2, 3, 4] AS nums RETURN extract(n IN nums WHERE n > 1 | n * 2)\"\n",
+    "    ]\n",
+    "})\n",
+    "class PredicateExtract(PredicateFunction):\n",
+    "    \"\"\"PredicateExtract function.\n",
+    "    \n",
+    "    Extracts values from an array with optional filtering.\n",
+    "    \"\"\"\n",
+    "\n",
+    "    def __init__(self):\n",
+    "        super().__init__(\"extract\")\n",
+    "\n",
+    "    def value(self) -> List[Any]:\n",
+    "        return list(self._extract())\n",
+    "    \n",
+    "    def _extract(self) -> Iterator[Any]:\n",
+    "        self.reference.referred = self._value_holder\n",
+    "        array = self.array.value()\n",
+    "        if array is None or not isinstance(array, list):\n",
+    "            raise ValueError(\"Invalid array for extract function\")\n",
+    "        \n",
+    "        for item in array:\n",
+    "            self._value_holder.holder = item\n",
+    "            if self.where is None or self.where.value():\n",
+    "                yield self._return.value()\n",
+    "\n",
+    "@FunctionDef({\n",
+    "    \"description\": \"Checks if any element in the array satisfies the condition. Uses list comprehension syntax: any(variable IN array [WHERE condition])\",\n",
+    "    \"category\": \"predicate\",\n",
+    "    \"parameters\": [\n",
+    "        {\"name\": \"variable\", \"description\": \"Variable name to bind each element\", \"type\": \"string\"},\n",
+    "        {\"name\": \"array\", \"description\": \"Array to iterate over\", \"type\": \"array\"},\n",
+    "        {\"name\": \"where\", \"description\": \"Condition to check for each element\", \"type\": \"boolean\", \"required\": False}\n",
+    "    ],\n",
+    "    \"output\": {\"description\": \"True if any element satisfies the condition, otherwise false\", \"type\": \"boolean\", \"example\": True},\n",
+    "    \"examples\": [\n",
+    "        \"WITH [1, 2, 3] AS nums RETURN any(n IN nums | n > 2)\",\n",
+    "        \"WITH [1, 2, 3] AS nums RETURN any(n IN nums | n > 5)\"\n",
+    "    ]\n",
+    "})\n",
+    "class Any(PredicateFunction):\n",
+    "    \"\"\"Any function.\n",
+    "    \n",
+    "    Returns true if any element in the array satisfies the condition.\n",
+    "    \"\"\"\n",
+    "\n",
+    "    def __init__(self):\n",
+    "        super().__init__(\"any\")\n",
+    "\n",
+    "    def value(self) -> bool:\n",
+    "        return any(self._any())\n",
+    "    \n",
+    "    def _any(self) -> Iterator[bool]:\n",
+    "        self.reference.referred = self._value_holder\n",
+    "        array = self.array.value()\n",
+    "        if array is None or not isinstance(array, list):\n",
+    "            raise ValueError(\"Invalid array for any function\")\n",
+    "        \n",
+    "        for item in array:\n",
+    "            self._value_holder.holder = item\n",
+    "            if self.where is None or self.where.value():\n",
+    "                yield True"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7",
+   "metadata": {},
+   "source": [
+    "Test functions just created"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "runner: Runner = Runner(\"\"\"\n",
+    "    return uppercase(\"hello world\") as uppercased\n",
+    "\"\"\")\n",
+    "await runner.run()\n",
+    "for record in runner.results:\n",
+    "    print(record)\n",
+    "\n",
+    "runner: Runner = Runner(\"\"\"\n",
+    "    unwind [1, 2, 3, 4, 5] as num\n",
+    "    return product(num) as total_product\n",
+    "\"\"\")\n",
+    "await runner.run()\n",
+    "for record in runner.results:\n",
+    "    print(record)\n",
+    "\n",
+    "runner: Runner = Runner(\"\"\"\n",
+    "    load json from get(\"https://catfact.ninja/fact\") as result\n",
+    "    return result.fact as cat_fact\n",
+    "\"\"\")\n",
+    "await runner.run()\n",
+    "for record in runner.results:\n",
+    "    print(record)\n",
+    "\n",
+    "runner: Runner = Runner(\"\"\"\n",
+    "    load json from json_file(\"../misc/data/test.json\") as result\n",
+    "    unwind result as entry\n",
+    "    return entry\n",
+    "\"\"\")\n",
+    "await runner.run()\n",
+    "for record in runner.results:\n",
+    "    print(record)\n",
+    "\n",
+    "runner: Runner = Runner(\"\"\"\n",
+    "    with [\n",
+    "        {\"age\": 25, \"name\": \"Alice\"},\n",
+    "        {\"age\": 30, \"name\": \"Bob\"},\n",
+    "        {\"age\": 22, \"name\": \"Charlie\"},\n",
+    "        {\"age\": 28, \"name\": \"Diana\"}\n",
+    "    ] as people\n",
+    "    return extract(p IN people | p.name WHERE p.age > 25) as names_over_25\n",
+    "\"\"\")\n",
+    "await runner.run()\n",
+    "for record in runner.results:\n",
+    "    print(record)\n",
+    "\n",
+    "runner: Runner = Runner(\"\"\"\n",
+    "    with [1, 2, 3, 4, 5] as numbers\n",
+    "    return any(n IN numbers | n where n > 6) as has_greater_than_3\n",
+    "\"\"\")\n",
+    "await runner.run()\n",
+    "for record in runner.results:\n",
+    "    print(record)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9",
+   "metadata": {},
+   "source": [
+    "List functions"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "runner: Runner = Runner(\"\"\"\n",
+    "    unwind functions() as func\n",
+    "    return func\n",
+    "\"\"\")\n",
+    "await runner.run()\n",
+    "for record in runner.results:\n",
+    "    print(record)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11",
+   "metadata": {},
+   "source": [
+    "Test virtual graph"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await Runner(\"\"\"\n",
+    "    create virtual (:User) as {\n",
+    "        load json from json_file(\n",
+    "            \"../misc/data/users.json\"\n",
+    "        ) as users\n",
+    "        unwind users as user\n",
+    "        return user.id as id,\n",
+    "            user.name as name,\n",
+    "            user.title as title,\n",
+    "            user.department as department,\n",
+    "            user.email as email,\n",
+    "            user.managerId as managerId\n",
+    "    }\n",
+    "\"\"\").run()\n",
+    "\n",
+    "await Runner(\"\"\"\n",
+    "    create virtual (:User)-[:MANAGED_BY]->(:User) as {\n",
+    "        load json from json_file(\n",
+    "            \"../misc/data/users.json\"\n",
+    "        ) as users\n",
+    "        unwind users as user\n",
+    "        return user.id as left_id, user.managerId as right_id\n",
+    "    }\n",
+    "\"\"\").run()\n",
+    "\n",
+    "runner: Runner = Runner(\"\"\"\n",
+    "    MATCH p=(u:User)-[:MANAGED_BY*]->(ceo:User)\n",
+    "    WHERE NOT (ceo)-[:MANAGED_BY]->(:User)\n",
+    "    and any(n IN nodes(p) | n where n.department = \"Litigation\")\n",
+    "    RETURN\n",
+    "        u.name as employee,\n",
+    "        extract(n IN nodes(p) | n.name) as management_chain\n",
+    "\"\"\")\n",
+    "await runner.run()\n",
+    "print(f\"Total results: {len(runner.results)}\")\n",
+    "for record in runner.results:\n",
+    "    print(record)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "13",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "flowquery",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.19"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}