flowquery 1.0.52 → 1.0.54

package/README.md

@@ -30,7 +30,7 @@ The combination of graph querying and pipeline processing makes FlowQuery ideal
                                                                  └──────────┘
 ```
 
-See the [Language Reference](#language-reference) and [Quick Cheat Sheet](#quick-cheat-sheet) for full syntax documentation.
+See the [Language Reference](#language-reference) and [Quick Cheat Sheet](#quick-cheat-sheet) for full syntax documentation. For a complete worked example, see [Virtual Org Chart](#virtual-org-chart).
 
 FlowQuery is written in TypeScript and runs both in the browser and in Node.js as a self-contained single-file JavaScript library. A pure Python implementation of FlowQuery with full functional fidelity is also available in the [flowquery-py](./flowquery-py) sub-folder (`pip install flowquery`).
 
@@ -393,6 +393,29 @@ RETURN sum(n IN [1, 2, 3] | n) AS sum                // 6
 RETURN sum(n IN [1+2+3, 2, 3] | n^2) AS sum          // 49
 ```
 
+### Boolean Predicate Functions
+
+Test list elements against a condition. Follow standard Cypher syntax.
+
+```cypher
+// any — true if at least one element matches
+RETURN any(n IN [1, 2, 3] WHERE n > 2)               // true
+
+// all — true if every element matches
+RETURN all(n IN [2, 4, 6] WHERE n > 0)               // true
+
+// none — true if no element matches
+RETURN none(n IN [1, 2, 3] WHERE n > 5)              // true
+
+// single — true if exactly one element matches
+RETURN single(n IN [1, 2, 3] WHERE n > 2)            // true
+
+// In a WHERE clause
+UNWIND [[1,2,3], [4,5,6]] AS nums
+WITH nums WHERE any(n IN nums WHERE n > 4)
+RETURN nums                                          // [4, 5, 6]
+```
+
 ### Aggregate Functions
 
 Used in `RETURN` or `WITH` to group and reduce rows. Non-aggregated expressions define grouping keys. Aggregate functions cannot be nested.
@@ -552,6 +575,44 @@ MATCH (a:Person), (b:Person) WHERE (a)-[:KNOWS]->(b) RETURN a.name, b.name
 MATCH (a:Person) WHERE NOT (a)-[:KNOWS]->(:Person) RETURN a.name
 ```
 
+**Subquery Expressions:** `EXISTS`, `COUNT`, and `COLLECT` evaluate a full subquery as an expression. The subquery can reference outer-scope variables and supports the complete FlowQuery pipeline (MATCH, WITH, WHERE, UNWIND, LOAD, etc.).
+
+```cypher
+// EXISTS — returns true if the subquery produces any rows
+MATCH (p:Person)
+WHERE EXISTS {
+    MATCH (p)-[:KNOWS]->(friend:Person)
+    WHERE friend.age > 30
+}
+RETURN p.name
+
+// NOT EXISTS — negate with NOT
+MATCH (p:Person)
+WHERE NOT EXISTS { MATCH (p)-[:KNOWS]->(:Person) }
+RETURN p.name
+
+// COUNT — returns the number of rows the subquery produces
+MATCH (p:Person)
+WHERE COUNT { MATCH (p)-[:KNOWS]->(:Person) } > 2
+RETURN p.name
+
+// COUNT in RETURN
+MATCH (p:Person)
+RETURN p.name, COUNT { MATCH (p)-[:KNOWS]->(:Person) } AS friendCount
+
+// COLLECT — returns a list of single-column values from the subquery
+MATCH (p:Person)
+RETURN COLLECT {
+    MATCH (p)-[:KNOWS]->(friend:Person)
+    RETURN friend.name
+} AS friends
+
+// COLLECT with IN
+MATCH (p:Person)
+WHERE 'Alice' IN COLLECT { MATCH (p)-[:KNOWS]->(f:Person) RETURN f.name }
+RETURN p.name
+```
+
 **Node reference reuse across MATCH clauses:**
 
 ```cypher
@@ -674,6 +735,8 @@ RETURN f.name, f.description, f.category
 │  CONTAINS  ·  NOT CONTAINS                                  │
 │  STARTS WITH  ·  NOT STARTS WITH                            │
 │  ENDS WITH  ·  NOT ENDS WITH                                │
+│  EXISTS { subquery }  ·  NOT EXISTS { subquery }            │
+│  COUNT { subquery }  ·  COLLECT { subquery }                │
 ├─────────────────────────────────────────────────────────────┤
 │  EXPRESSIONS                                                │
 ├─────────────────────────────────────────────────────────────┤
@@ -698,6 +761,10 @@ RETURN f.name, f.description, f.category
 │  sum(x)  avg(x)  count(x)  min(x)  max(x)  collect(x)       │
 │  count(DISTINCT x)  ·  collect(DISTINCT x)                  │
 │  sum(v IN list | expr [WHERE cond])  -- inline predicate    │
+│  any(v IN list WHERE cond)            -- true if any match  │
+│  all(v IN list WHERE cond)            -- true if all match  │
+│  none(v IN list WHERE cond)           -- true if none match │
+│  single(v IN list WHERE cond)         -- true if one match  │
 ├─────────────────────────────────────────────────────────────┤
 │  SCALAR FUNCTIONS                                           │
 ├─────────────────────────────────────────────────────────────┤
@@ -891,6 +958,92 @@ WITH f WHERE f.name = 'double'
 RETURN f.name AS name, f.description AS description, f.category AS category
 ```
 
+## Examples
+
+### Virtual Org Chart
+
+This single multi-statement query creates a virtual graph for a fictitious company — complete with employees, skills, phone numbers, and a management chain — then queries it to produce an org chart. [Try live!](https://microsoft.github.io/FlowQuery/?rZXPbtNAEMbFhUMOReXAeW4OwkH521ZBQgolrVQlSogDQlRVtdjTeKm9a603Bavqw_AAPEVfDO16s_EmEVElfPHuzGf7N9-M7UN4BfX-MM0SXiC-hkEA9zUAgJdwqc_quKdRH1o-MJJiH7yACAKnMTLP1-kf_PucykSlTocTE6weEWZEyBSZ7IM3_IXhUtI71MIs5kxd-KbV6PV6jWar2fR8yG9pkuR9uPQCKYjEReH54I2QRCjymGZqd0YZYSF6Vw--C9q2oGMiwmUOM3qHgnh-FfTLFPgNDNmCMkRB2ULTuKBOchO03Ww5oAMRxlRiKJdCVeadJnwZqcUYmeT6JlukHUs6FbQgMCUSEw2yRToVPFqG0prrkLrJTdLOBumMkyglWVbW5Q0YSQpJw1xtPn_dpuxayguSYg4fBOe3Sl2lDJBRLqyhBuVJfrYdynmRYRAKmqmyvGkhY67mzTsXJIs_jbYxexZzRBl8i4np6f_G7LhmLnMNGBS5xFR7-BHvJlm-DXhkAQepeoMueMxyXVQF0LQSxoSRxW7Afd12fQxCsUw1FpEEdLNzqjkDSW4x5kmEAsaLVG4TH1viOU8ff-dwTkT4-Ids9p7fyJ9EoGvrk0ztuqYi0fVtDMEcc7nzPTqxnGdE0pTAIGkEpMDI9XYX55Moew7leibHI2vwlGaYUIaq_xrySn1SBYZcRHp_YDZvaaQyNPJXAVWCCqmzDa7wVWK1XlcPsNKt61DK9c7eSFejcnphw2U5Kl6uag_vaofuP6Fx2Z8Np5PZPLieT64a-_8WCd7Ia_MlFnQRl5tWtWtW0tkv6VYl7Z2S3n7JUVXS2Sk5rkq6OyUnruTfHTZXqbRZWttXN9GXmrWy_gXUce1v7RnUt_x_X08XoqI50A_FcnzWxyAANBrfKOwsWYVcjxNWR8ikK2NkNOUUVR9SjpNJm2mqpMtImU8XwqXUvmVcyHzOa88dBN9U9Bc)
+
+```cypher
+CREATE VIRTUAL (:Employee) AS {
+    UNWIND [
+        {id: 1, name: 'Sara Chen',     jobTitle: 'CEO',                 department: 'Executive',   phone: '+1-555-0100', skills: ['Strategy', 'Leadership', 'Finance']},
+        {id: 2, name: 'Marcus Rivera', jobTitle: 'VP of Engineering',   department: 'Engineering', phone: '+1-555-0201', skills: ['Architecture', 'Cloud', 'Mentoring']},
+        {id: 3, name: 'Priya Patel',   jobTitle: 'VP of Product',       department: 'Product',     phone: '+1-555-0301', skills: ['Roadmapping', 'Analytics', 'UX']},
+        {id: 4, name: 'James Brooks',  jobTitle: 'Senior Engineer',     department: 'Engineering', phone: '+1-555-0202', skills: ['TypeScript', 'Python', 'GraphQL']},
+        {id: 5, name: 'Lin Zhang',     jobTitle: 'Senior Engineer',     department: 'Engineering', phone: '+1-555-0203', skills: ['Rust', 'Systems', 'DevOps']},
+        {id: 6, name: 'Amara Johnson', jobTitle: 'Product Manager',     department: 'Product',     phone: '+1-555-0302', skills: ['Scrum', 'Data Analysis', 'Stakeholder Mgmt']},
+        {id: 7, name: 'Tomás García',  jobTitle: 'Software Engineer',   department: 'Engineering', phone: '+1-555-0204', skills: ['React', 'TypeScript', 'Testing']},
+        {id: 8, name: 'Fatima Al-Sayed', jobTitle: 'Software Engineer', department: 'Engineering', phone: '+1-555-0205', skills: ['Python', 'ML', 'Data Pipelines']}
+    ] AS record
+    RETURN record.id AS id, record.name AS name, record.jobTitle AS jobTitle,
+           record.department AS department, record.phone AS phone, record.skills AS skills
+};
+CREATE VIRTUAL (:Employee)-[:REPORTS_TO]-(:Employee) AS {
+    UNWIND [
+        {left_id: 2, right_id: 1},
+        {left_id: 3, right_id: 1},
+        {left_id: 4, right_id: 2},
+        {left_id: 5, right_id: 2},
+        {left_id: 6, right_id: 3},
+        {left_id: 7, right_id: 4},
+        {left_id: 8, right_id: 4}
+    ] AS record
+    RETURN record.left_id AS left_id, record.right_id AS right_id
+};
+MATCH (e:Employee)
+OPTIONAL MATCH (e)-[:REPORTS_TO]->(mgr:Employee)
+RETURN
+    e.name           AS employee,
+    e.jobTitle       AS title,
+    e.department     AS department,
+    e.phone          AS phone,
+    e.skills         AS skills,
+    mgr.name         AS reportsTo
+ORDER BY e.department, e.name
+```
+
+Output:
+
+| employee        | title             | department  | phone       | skills                                   | reportsTo     |
+| --------------- | ----------------- | ----------- | ----------- | ---------------------------------------- | ------------- |
+| Fatima Al-Sayed | Software Engineer | Engineering | +1-555-0205 | [Python, ML, Data Pipelines]             | James Brooks  |
+| James Brooks    | Senior Engineer   | Engineering | +1-555-0202 | [TypeScript, Python, GraphQL]            | Marcus Rivera |
+| Lin Zhang       | Senior Engineer   | Engineering | +1-555-0203 | [Rust, Systems, DevOps]                  | Marcus Rivera |
+| Marcus Rivera   | VP of Engineering | Engineering | +1-555-0201 | [Architecture, Cloud, Mentoring]         | Sara Chen     |
+| Tomás García    | Software Engineer | Engineering | +1-555-0204 | [React, TypeScript, Testing]             | James Brooks  |
+| Sara Chen       | CEO               | Executive   | +1-555-0100 | [Strategy, Leadership, Finance]          | null          |
+| Amara Johnson   | Product Manager   | Product     | +1-555-0302 | [Scrum, Data Analysis, Stakeholder Mgmt] | Priya Patel   |
+| Priya Patel     | VP of Product     | Product     | +1-555-0301 | [Roadmapping, Analytics, UX]             | Sara Chen     |
+
+You can further explore the graph — for example, find the full management chain from any employee up to the CEO:
+
+```cypher
+MATCH (e:Employee)-[:REPORTS_TO*1..]->(mgr:Employee)
+WHERE e.name = 'Tomás García'
+RETURN e.name AS employee, collect(mgr.name) AS managementChain
+// [{ employee: "Tomás García", managementChain: ["James Brooks", "Marcus Rivera", "Sara Chen"] }]
+```
+
+Or find each manager's direct reports:
+
+```cypher
+MATCH (dr:Employee)-[:REPORTS_TO]->(mgr:Employee)
+RETURN mgr.name AS manager, collect(dr.name) AS directReports
+ORDER BY manager
+```
+
+Or find all employees who share a skill:
+
+```cypher
+MATCH (a:Employee), (b:Employee)
+WHERE a.id < b.id
+WITH a, b, [s IN a.skills WHERE s IN b.skills] AS shared
+WHERE size(shared) > 0
+RETURN a.name AS employee1, b.name AS employee2, shared AS sharedSkills
+ORDER BY size(shared) DESC
+```
+
 ## Contributing
 
 This project welcomes contributions and suggestions. Most contributions require you to agree to a