> ## Documentation Index
> Fetch the complete documentation index at: https://gql.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# OPTIONAL MATCH

Use OPTIONAL MATCH to find patterns that might not exist, returning empty values when patterns don't match. The OPTIONAL MATCH clause works like MATCH but allows parts of the pattern to be missing. It preserves nulls in the result when the pattern does not fully match, similar to a left outer join in
relational databases.

### Return nodes where the relationship may not exist

Suppose we are interested all the persons who have income of greater and 185000 and not live in Capitola.

```mermaid theme={null}

%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#F1FA8C','secondaryColor':'#F1FA8C','background':'#282A36'}}}%%
graph LR

    subgraph row1[" "]

    saqib[<b>:person</b><br/>name: Saqib👨<br/>income: 375000]
    scott[<b>:person</b><br/>name: Scott 👨<br/>income: 205000]
    fatima[<b>:person</b><br/>name: Fatima 👩<br/>income: 195000]
    hannah[<b>:person</b><br/>name: Hannah 👩<br/>income: 185000]
    zainab[<b>:person</b><br/>name: Zainab 👩<br/>income: 190000]
    capitola[<b>:city</b><br/>name:Capitola]

    end

    subgraph row2[" "]
    eleni[<b>:person</b><br/>name: Eleni 👩<br/>income: 185000]
    uroosa[<b>:person</b><br/>name: Uroosa 👩<br/>income: 175000]
    angela[<b>:person</b><br/>name: Angela 👩<br/>income: 195000]
    maryam[<b>:person</b><br/>name: Maryam 👩<br/>income: 155000]
    santacruz[<b>:city</b><br/>name:Santa Cruz]
    end

    subgraph row3[" "]
    laila[<b>:person</b><br/>name: Laila 👩<br/>income: 180000]
    huda[<b>:person</b><br/>name: Huda 👩<br/>income: 172000]
    end

    %% saqib -->|:relationship<br/>type: co-worker| fatima
    %% fatima -->|:relationship<br/>type: friend| eleni
    %% eleni -->|:relationship<br/>type: friend| uroosa
    %% saqib -->|:relationship<br/>type: friend| angela
    %% angela -->|:relationship<br/>type: co-worker| scott
    %% scott -->|:relationship<br/>type: friend| uroosa


    saqib -->|<b>:lives_in</b>| capitola
    scott -->|<b>:lives_in</b>| capitola
    fatima -->|<b>:lives_in</b>| capitola
    hannah -->|<b>:lives_in</b>| capitola
    zainab -->|<b>:lives_in</b>| capitola



    angela -->|<b>:lives_in</b>| santacruz
    uroosa -->|<b>:lives_in</b>| santacruz
    eleni -->|<b>:lives_in</b>| santacruz
    maryam -->|<b>:lives_in</b>| santacruz


    classDef nodes fill:#BD93F9,stroke-width:0px
    class saqib,fatima,angela,uroosa,eleni,scott,maryam,zainab,hannah,huda,laila nodes

    classDef subgraphStyle fill:#282A36, stroke-width:0px
    class row1,row2,row3 subgraphStyle
```

```gql theme={null}

MATCH (resident:person WHERE resident.income > 185000)
OPTIONAL MATCH (resident)-[:lives_is]->(c:city)
    WHERE c.name <> 'Capitola' 
RETURN p.name as Person, c.name as City
```

This query finds all Person nodes where the income is greater than 185000, and optionally matches cities they're connected to (excluding Capitola). If a person isn't connected to any city, the City column returns empty, but the person is still included in the results.

Output

The optional match ensures that people without city connections are still returned

| Person | City       |
| ------ | ---------- |
| Angela | Santa Cruz |
| Huda   |            |