Cypher Basics — Finding and Filtering Nodes

Open Ontological Portal and run the basic Cypher clauses — MATCH, WHERE, RETURN, ORDER BY and LIMIT — one at a time on the sample data.

Cypher: queries you draw#

Cypher is a query language that describes graph structure the way you would draw it. It started in Neo4j and is now the basis of GQL, the ISO standard graph query language.

It is easy to understand if you compare it with SQL's SELECT … FROM … WHERE.

Opening the Portal#

On Home, click the Ontological Portal card. In the graph selector at the top left, choose sample. Every example in Part 4 runs on the sample graph.

Your first query#

MATCH (s:Supplier)
RETURN s.supplier_id, s.name, s.country, s.tier

MATCH specifies the graph pattern to find, and RETURN specifies what to include in the results. To get whole nodes, write RETURN s. That returns an object with all of the node's properties, and the result card gets a Graph view.

Filtering — WHERE#

MATCH (s:Supplier)
WHERE s.country = 'China' AND s.tier = 1
RETURN s.name

The result is one supplier, Shenzhen Goldline PCB. These are the conditions you can use in WHERE.

If there is only one condition, you can write the property and value directly in the pattern.

MATCH (s:Supplier {supplier_id: 'S-CN-01'})
RETURN s

Sorting and limiting — ORDER BY · SKIP · LIMIT#

The three largest purchase orders:

MATCH (po:PurchaseOrder)
RETURN po.po_id, po.amount_usd, po.status
ORDER BY po.amount_usd DESC
LIMIT 3

You can sort by several keys, as in ORDER BY a, b DESC. SKIP 2 LIMIT 3 means “skip two, then take three”, which is how you split results into pages. Use AS to rename a column, as in RETURN po.po_id AS po_number (non-English names work too).

Removing duplicates and counting#

MATCH (s:Supplier) RETURN DISTINCT s.country

MATCH (s:Supplier) RETURN count(s) AS suppliers

The first query returns three rows (Vietnam, Korea, China), and the second returns 5.

Transforming values — functions and CASE#

MATCH (sh:Shipment)
RETURN sh.shipment_no,
       CASE WHEN sh.delay_days > 3 THEN 'Delayed'
            WHEN sh.delay_days > 0 THEN 'Watch'
            ELSE 'OK' END AS status
ORDER BY sh.shipment_no

These are the functions Ontological DB supports. If you use a function that is not on this list, the engine returns an error that shows the list.

Three ways to view results#

Choose a view at the top right of the result card.

• Table — shows the results as a table. This is the view you will use most.
• JSON — shows node objects as they are. This is the same format your app code receives (Chapter 19).
• SQL — the PostgreSQL SQL your Cypher was translated into. It shows how Ontological DB runs the query (Chapter 9).

MATCH (po:PurchaseOrder) WHERE po.status = 'OPEN'
RETURN po.po_id, po.amount_usd ORDER BY po.amount_usd

MATCH (sh:Shipment) WHERE sh.ship_status IN ['IN_TRANSIT', 'CUSTOMS_HOLD']
RETURN sh.shipment_no, sh.eta

MATCH (cu:Customer) RETURN count(cu) AS customers

MATCH (c:Claim) WHERE c.severity = 'HIGH' RETURN c.ticket_no, c.subject