Cypher-backed Views

Cypher-backed Views enable users to define views based on a Cypher query. The definitions of the Cypher-backed Views are stored in JSON format in a text file. The file is then passed to the connector via the connection URL. Cypher-backed Views include the metadata and schema for the view as well as the corresponding Cypher query.

To use Cypher-backed Views, in the connection URL, specify the full path to the View Definition file using the ViewDefinitionFile property. For details, see ViewDefinitionFile.

For more information about Cypher-backed Views, see the following sections: 

View Definition File Specification

The View Definition file can define multiple schemas. Using these schemas, users can define the Cypher-backed View tables. By default, the Cypher-backed View tables are categorized under schema: View, unless a different name is provided in the View Definition file.

Note:

  • The Node and Relationship schemas cannot be used to view Cyper-backed View tables. For details about Node and Relationship schemas, see Catalog and Schema Support.
  • Before connecting to a database using a View Definition file, make sure that the database contains the nodes or relationships present in the Cypher query provided for views.

View Definition File Overview

The View Definition file is a JSON formatted file. The View Definition begins with a JSON object structure containing a single property:

Property Name JSON Structure Required Default Value

Schemas

Array containing schema
definitions as array elements.

Yes

 N/A

Each schema definition is encapsulated in a JSON object structure with the following properties:

Property Name JSON Structure Required Default Value

Name

String

No

 View
Hidden Boolean No False
Views Array containing Cypher-backed View table definitions as array elements for the parent schema. Yes N/A

Each Cypher-backed View table definition is encapsulated in a JSON object structure with the following properties:

Property Name JSON Structure Required Default Value

Name

String

Yes

 N/A
Hidden Boolean No False
CypherQuery String Yes N/A
Columns Array containing Cypher-backed View column definitions as array elements for the parent table. Yes N/A

Lastly, each Cypher-backed View column definition is encapsulated in a JSON object structure with the following properties:

Property Name JSON Structure Required Default Value

Name

String

Yes

 N/A
SourceName String No N/A
Mandatory Boolean No False
Hidden Boolean No False
Neo4jType String or Array containing Neo4j types as JSON string values. No String

Comprehensive View Definition File Example

In this example, we asked the connector to expose, via applications, a new Schema named PlayersBio and a table named PlayerProfile. The PlayerProfile table represents the Cypher-backed View provided via the Cypher query present in the CypherQuery field below. The columns that exist within PlayerProfile are: _NodeId_, Last Name, Country, Ranking, and DOB.

Note:

The top-level structure needs to have a JSON object structure containing a single key-value pair. The key present in the example below is Schemas.

The following example displays the file format and the various properties needed for defining the Cypher-backed View tables:

{

"Schemas": [

{

"Name": "PlayersBio",

"Hidden": false,

"Views": [

{

"Name": "PlayerProfile",

"CypherQuery": "MATCH (node:Player) RETURN

ID(node), node.LastName as lastName,

node.Country, node.Ranking, node.DOB",

"Columns": [

{

"Name": "_NodeId_",

"SourceName": "ID(node)",

"Neo4jType": ["Long"],

"Mandatory": true,

"Hidden": false

},

{

"Name": "Last Name",

"SourceName": "lastName",

"Neo4jType": ["String"],

"Mandatory": false,

"Hidden": false

},

{

"Name": "Country",

"SourceName": "node.Country",

"Neo4jType": "String",

"Mandatory": false,

"Hidden": false

},

{

"Name": "Ranking",

"SourceName": "node.Ranking",

"Neo4jType": ["String","Long"],

"Mandatory": false,

"Hidden": false

},

{

"Name": "DOB",

"SourceName": "node.DOB",

"Neo4jType": ["Date"],

"Mandatory": false,

"Hidden": false

}

]

}

]

}

]

}

For information about the key-value pairs in the example above, see the following:

Schemas (ref. - "Schemas": [...])

A JSON array structure within which schema definitions are provided.

Default Value Data Type Required

None

Array of JSON objects, where each object contains a schema definition.

Yes

The schema definition present as an array value within Schemas contains the following keys:

Name (ref. - "Name": "PlayersBio")

The name of the view schema which contains Cypher-backed View tables.

Default Value Data Type Required

View

String

No

Note:

Duplicate schema names are not allowed by the connector. The matching performed on schema names is case-sensitive, therefore schema names such as TestView and testview are not considered duplicates.

Hidden (ref. - "Hidden": false)

Indicates whether the defined view schema is displayed in applications.

Default Value Data Type Required

False

Boolean

No

Views (ref. - "Views": [...])

A JSON array structure that contains the view table definitions.

Default Value Data Type Required

None

Array of JSON objects, where each object contains a view table definition.

Yes

The view table definition contains the following keys:

Name (ref. - "Name": "PlayerProfile")

The Name of the Cypher-backed View table that is displayed in applications.

Default Value Data Type Required

None

String

Yes

Note:

Duplicate view table names are not allowed by the connector. However, the matching performed on table names is case-sensitive, therefore names such as TestViewTable and testviewtable are not considered duplicates.

Hidden (ref. - "Hidden": false)

Key to indicate whether the defined view table is displayed in applications.

Default Value Data Type Required

False

Boolean

No

CypherQuery (ref. - "CypherQuery": "MATCH (node:Player)...")

The Cypher query used for obtaining results for the Cypher-backed View table.

Default Value Data Type Required

None

String

Yes

Note:

  • The Cypher query must return only specific properties of the nodes or relationships and not the full nodes or relationships.
  • The connector does not validate the Cypher query string, therefore the Cypher query provided via the CypherQuery field is executed if the view gets queried. Make sure that the read-only query is provided in the CypherQuery field. If not, the data is manipulated when the view is queried.

Columns (ref. - "Columns": [...])

A JSON array structure that contains the view column definitions.

Default Value Data Type Required

None

Array of JSON objects, where each object contains a view column definition.

Yes

The view column definition contains the following keys:

Name (ref. - "Name": "_NodeId_")

The view column name that is displayed in applications. For details on the value specification of Name for column when SourceName is not provided, see the definition of SourceName below.

Default Value Data Type Required

None

String

Yes

Note:

Duplicate view column names are not allowed by the connector. However, the matching performed on column names is case-insensitive and therefore names such as TestCol and testcol are considered duplicates.

SourceName (ref. - "SourceName": "ID(node)")

The Neo4j property name provided verbatim in the Cypher query. The SourceName field is used by the connector when retrieving data for the column being queried.

If an alias name is used for the Neo4j property name in the provided Cypher query, the source name must match the alias name. In the example above, this is shown in column definition ("SourceName": "lastName").

If the source name is not provided, the column's name attribute ("Name") has to match the referenced Neo4j property name from the Cypher query so that the connector can locate data for the column when retrieving result set.

Default Value Data Type Required

None

String

No

To change the column name displayed by applications of the referenced Neo4j property returned in the view's Cypher query:

  • In the SourceName field, define the original Neo4j property name returned.
  • In the column's Name field, define the name you want the application to display.

For example, to change the column name from ID(node) to PlayerID, define the column's name as "Name": "PlayerID" and the column's source name as "SourceName": "ID(node)".

If you do not want to change the column name, do not define SourceName and define the column name as "Name": "ID(node)".

Neo4jType (ref. - "Neo4jType": ["Long"])

The Neo4j type for the view column. The Neo4j type can be provided as an individual string value, like "Neo4jType": "Long", or as an array of string values.

If the Neo4j property contains values of different types, the connector handles the data type coercion in case multiple types are provided for a column. For example, if a property contains values of Date, String and Long types, the key value pair for the Neo4j type is "Neo4jType": ["Date", "String", "Long"].

The following Neo4j types can be provided as values to the connector for Cypher-backed Views:

Boolean

BooleanArray

ByteArray

Long LongArray Integer
IntegerArray Double DoubleArray
Float String StringArray
Point PointArray Date
DateArray LocalTime LocalTimeArray
Time TimeArray LocalDateTime
LocalDateTimeArray DateTime DateTimeArray
Duration DurationArray  

Default Value Data Type Required

String

String or Array of string values

No

Note:

Any Neo4j data types that do not have a specific SQL mapping are mapped to SQL_VARCHAR. For details on mapping Neo4j types to SQL and Java types, see Data Types.

Mandatory (ref. - "Mandatory": true)

Indicates whether a column is nullable or not. Mandatory:false indicates nullability:true, while Mandatory:true indicates nullability:false.

Default Value Data Type Required

False

Boolean

No

Note:

When specifying whether a column is mandatory or not, check the existing constraint set on the respective property in the Neo4j graph before defining the Mandatory field.

For example, suppose a column or property contain nulls and Mandatory:true is specified. This is a contradiction because even though the graph does contain nulls for the column or property, by providing Mandatory:true instead of Mandatory:false, the connector incorrectly imposes nullability:false.

Hidden (ref. - "Hidden": false)

Indicates whether the defined view column is displayed by applications.

Default Value Data Type Required

False

Boolean

No

For example, you are connecting to a database called "neo4j" whose graph contains a node Player with the following data:

ID(node) : 12345
LastName : 'Federer'
Country : 'Switzerland'
Ranking : 2
DOB : 1981-08-08

Based on the above View Definition file example, the connector creates a table with the following information:

Catalog: neo4j
Schema : PlayersBio
Table : PlayerProfile
Columns: _NodeId_, Last Name, Country, Ranking and DOB

_NodeId_ Last Name Country Ranking DOB

12345

Federer

Switzerland

 2 1981-08-08

Succinct View Definition File Example

Based on the above View Definition file definitions, we can see that certain fields have default values and therefore can be omitted. A minimized version of the above View Definition file looks like the following:

{

"Schemas": [

{

"Views": [

{

"Name": "PlayerProfile",

"CypherQuery": "MATCH (node:Player RETURN

ID(node), node.LastName as lastName,

node.Country, node.Ranking, node.DOB",

"Columns": [

{

"Name": "ID(node)"

},

{

"Name": "lastName"

},

{

"Name": "node.Country"

},

{

"Name": "node.Ranking"

},

{

"Name": "node.DOB"

}

]

}

]

}

]

}

Based on the View Definition file above, the table created by the connector has the following information:

Catalog: neo4j
Schema : View
Table : PlayerProfile
Columns: ID(node), lastName, node.Country, node.Ranking and node.DOB

ID(node) lastName node.Country node.Ranking node.DOB

12345

Federer

Switzerland

 2 1981-08-08

Related topics