[[Reference]]
== Neosemantics Reference

Complete list of all available stored procedures, functions and extensions in Neosemantics.

=== Stored Procedures

==== RDF Config

[options="header"]
|===
| Procedure Name        | params           | Description and example usage
|n10s.graphconfig.init|
(optional) map with params from the table below
| Creates a graph config with the default settings plus the ones provided as parameter
|n10s.graphconfig.set | map with params from the table below | sets the specific property/value pairs in the Graph Config (only possible when graph is empty)
|n10s.graphconfig.show | - | Lists the current settings in the Graph Configuration
|n10s.graphconfig.drop|
| Removes the current Graph Config (only possible when graph is empty)
|===

===== Graph Config Params (global settings)
The following settings are valid throughout the life of your Neo4j graph and across multiple invocations of import/export/delete/preview/stream procedures.

[options="header"]
|===
| Param        | values(default)           | Description
| handleVocabUris      | 'SHORTEN', 'SHORTEN_STRICT','IGNORE','MAP','KEEP' ('SHORTEN')
a| include::includes/reference/handleVocabUris.adoc[]

| handleMultival | 'OVERWRITE', 'ARRAY' ('OVERWRITE')
a| include::includes/reference/handleMultival.adoc[]

| multivalPropList | list of strings ([])
a| include::includes/reference/multivalPropList.adoc[]

| keepLangTag | boolean (false)
a| include::includes/reference/keepLangTag.adoc[]

| handleRDFTypes      | 'LABELS', 'NODES','LABELS_AND_NODES' ('LABELS')
a| include::includes/reference/handleRDFTypes.adoc[]

| keepCustomDataTypes | boolean(false)
a| include::includes/reference/keepCustomDataTypes.adoc[]

| customDataTypePropList| list of strings ([])
a| include::includes/reference/customDataTypePropList.adoc[]

| applyNeo4jNaming | boolean (false)
a| include applyNeo4jNaming.adoc[]
|===


===== Ontology Import Specific Params


[options="header"]
|===
| Param        | values(default)           | Description
| classLabelName      | string ('Class') |  Label for classes in the ontology
| subClassOfRelName      | string ('SCO') |  Relationship name for `rdfs:subClassOf` statements
| dataTypePropertyLabelName      | string ('Property') |  Label for DataTypeProperty definitions (attributes)
| objectPropertyLabelName      | string ('Relationship') |  Label for ObjectProperty definitions (relationships)
| subPropertyOfRelName      | string ('SPO') |  Relationship  for `rdfs:subPropertyOf` statements
| domainRelName      | string ('DOMAIN') |  Domain relationship between Classes and DataTypeProperty/ObjectProperty
| rangeRelName      | string ('RANGE') |  Range relationship between Classes and DataTypeProperty/ObjectProperty
|===


==== RDF Import

[options="header"]
[cols="4,5,4"]

|===
| Procedure Name        | params           | Description and example usage
|n10s.rdf.import.fetch
a|
* URL of the dataset
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the table below
|Fetches RDF from a url (file or http) and stores it in Neo4j as a property graph. This procedure requires a unique constraint on :Resource(uri)
|n10s.rdf.import.inline
a|
* string containing an RDF fragment
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the table below
| Imports an RDF snippet passed as parameter and stores it in Neo4j as a property graph. Requires a unique constraint on :Resource(uri)
|n10s.onto.import.fetch
a|
* URL of the dataset
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the *ontology import* table below
| Imports classes, properties (dataType and Object), hierarchies thereof and domain and range info.
|n10s.onto.import.inline
a|
* Ontology as RDF snippet
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the *ontology import* table below
| Imports classes, properties (dataType and Object), hierarchies thereof and domain and range info.
|n10s.rdf.stream.fetch
a|
* URL of the dataset
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the table below
| Parses RDF and streams each triple as a record with <S,P,O> along with datatype and language tag for Literal values. No writing to the DB. This SP can be useful to preview a dataset or when you want to import into your Neo4j graph fragments of an RDF dataset in a custom way.
|n10s.rdf.stream.inline
a|
* string containing the Ontology as an RDF fragment
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the table below
| Parses RDF snippet passed as text and streams each triple as a record with <S,P,O> along with datatype and language tag for Literal values. No writing to the DB.
|n10s.rdf.preview.fetch
a|
* URL of the dataset
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the table below
| Parses RDF and produces virtual Nodes and relationships for preview in the Neo4j browser. No writing to the DB. Notice that this is adequate for a preliminary visual analysis of a SMALL dataset. By default loads the first 1K triples but this value can be overriden by setting the `limit` parameter. Think how many nodes you want rendered in your browser.
|n10s.rdf.preview.inline
a|
* string containing a valid RDF fragment
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the table below
| Parses an RDF fragment passed as parameter (no retrieval from url) and produces virtual Nodes and relationships for preview in the Neo4j browser. No writing to the DB
|n10s.rdf.delete.fetch
a|
* URL of the dataset
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the table below
| Deletes triples from Neo4j. Works on a graph resulted of importing RDF via import. Delete config must match the one used on import
|n10s.rdf.delete.inline
a|
* String containing a valid RDF fragment
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
* optional map with params from the table below
| Deletes from Neo4j the triples passed as first parameter. Works in the same way and takes the same parameters as `deleteRDF`.
|===

===== RDF Import Method Params (also valid for Ontology and SKOS import)

The following parameters are  specific to the import/preview/stream method.
[options="header"]
|===
| Param        | values(default)           | Description
| predicateExclusionList | list of strings ([]) | List  of predicates (full uri) that are to be ignored on parsing RDF and not stored in Neo4j.
| languageFilter      | ['en','fr','es',...] | when set, only literal properties with this language tag (or untagged ones) are imported
| headerParams      | map {} | parameters to be passed in the HTTP GET request or `payload` if POST request. <br> Example: `{ authorization: 'Basic user:pwd', Accept: 'application/rdf+xml'}`
| commitSize      | integer (25000) | commit a partial transaction every n triples
| nodeCacheSize      | integer (10000) | keep n nodes in cache to minimize reads from DB
| verifyUriSyntax | boolean (true) | by default, uri syntax is checked. This can be disable d by setting this parameter to `false`
|===


[[nsprefixmngmnt]]
==== Namespace Prefix Management

[options="header"]
|===
| Procedure Name        | params           | Description and example usage
|n10s.nsprefixes.add
a|
* prefix: string (like `owl`)
* namespace: namespace part of a uri (like `http://www.w3.org/2002/07/owl#`)
| Adds namespace - prefix pair definition to be used for RDF import/export
|n10s.nsprefixes.list | - | Lists all currently defined namespace prefix definitions
|n10s.nsprefixes.remove | prefix | removes a particular namespace prefix definition passed as parameter
|n10s.nsprefixes.removeAll | - | removes all namespace prefix definitions
|n10s.nsprefixes.addFromText | String | Extracts namespace prefix definitions from the text
passed as input (SPARQL, RDF/XML, Turtle) and adds each namespace-prefix pair so it can be used for RDF import/export
|===


==== Model Mapping

[options="header"]
|===
| Procedure Name        | params           | Description and example usage
| n10s.mapping.addSchema
a| * URL of the schema/vocabulary/ontology
* prefix to be used in serialisations | Creates a reference to a vocabulary. Needed to define mappings.
| n10s.mapping.dropSchema
a|
* URL of the schema/vocabulary/ontology| Deletes a vocabulary reference and all associated mappings.
| n10s.mapping.listSchemas
a| * optional filter string |  Returns all vocabulary references. When filter string is set, only schemas containing the search string in their uri or in the associated prefix are returned.
| n10s.mapping.addCommonSchemas      | no prams | Creates references to a number of popular vocabularies including schema.org, Dublin Core, SKOS, OWL, etc
| n10s.mapping.addMappingToSchema
a| * URL of the schema/voc/ontology
* The name of the element in the Neo4j graph (a property name, a label or a relationship type)
* The matching element (Class, DataTypeProperty or ObjectProperty) in the public schema. Only the local name of the element |
Creates a mapping for an element in the Neo4j DB schema to a vocabulary element
| n10s.mapping.dropMapping      |
* mapped DB element name to remove the mapping |
Returns an output text message indicating success/failure of the deletion
| n10s.mapping.listMappings
a|
* optional filter string
| Returns a list with all the currently defined mappings. Whe filter string is passed, only mappings containing the string in the
DB element name or the schema element URI are returned
|===

==== SHACL Validations

[options="header"]
|===
| Stored Proc Name        | params           | Description
|n10s.validation.shacl.import.fetch
a|
* URL of the dataset
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
|Fetches the SHACL constraint definitions from a url (file or http) and compiles them into an  executable form in Neo4j
|n10s.validation.shacl.import.inline
a|
* string containing an RDF fragment
* serialization format (valid formats: Turtle, N-Triples, JSON-LD, TriG, RDF/XML)
|Loads the the SHACL constraint passed as parameter (as an RDF fragment) and compiles them into an  executable form in Neo4j
|n10s.validation.shacl.listShapes
| - | Lists all constraint currently loaded (active)
|n10s.validation.shacl.validate
|  - | validates the Neo4j graph against the currently loaded (active) constraints producing a report with all violations
|n10s.validation.shacl.validateSet
| a list of nodes | validates the list of nodes passed as parameter against the currently loaded (active) constraints producing a report with all violations
|n10s.validation.shacl.validateTransaction
| transaction context parameters | validates the elements in the graph changed by the current transaction against the currently loaded constraints producing the transaction to roll back if the transaction introduces any violations in the graph or to succeed if not. Example of use in section <<RunningValidation>>
|===

==== Inferencing

[options="header"]
|===
| Stored Proc Name        | params           | Description
|n10s.inference.nodesLabelled
a|
* a string with a label name
* parameters as described in table below | returns all nodes with label 'label' or its sublabels
|n10s.inference.nodesInCategory
a|
* a node representing the category
* parameters as described in table below  | returns all nodes connected to Node 'catNode' or its subcategories
|n10s.inference.getRels
a|
* a start node
* a (real or 'virtual') relationship type
* parameters as described in table below | returns all relationships of type 'virtRel' or its subtypes along with the target nodes
|n10s.inference.hasLabel *(function)*
a| * a node
* a label name as a string
* parameters as described in table below | checks whether node is explicitly or implicitly labeled as 'label'
|n10s.inference.inCategory *(function)*
a|
* a node representing an instance
* a node representing a category
* parameters as described in table below | checks whether node is explicitly or implicitly in a category
|===

===== Inferencing Params

====== Parameters for method n10s.inference.nodesLabelled and function n10s.inference.hasLabel

[options="header"]
|===
| Param        | values(default)           | Description
| catLabel | String ('Label') | Label used for nodes describing categories.
| catNameProp | String ('name') | property name containing the name of the category.
| subCatRel | String ('SLO') | relationship type connecting a child category to its parent
|===

====== Parameters for method n10s.inference.nodesInCategory and function n10s.inference.inCategory

[options="header"]
|===
| Param        | values(default)           | Description
| inCatRel | String ('IN_CAT') | relationship type connecting an instance node to the category node.
| subCatRel | String ('SCO') | relationship type connecting a child category to its parent.
|===

====== Parameters for method n10s.inference.getRels

[options="header"]
|===
| Param        | values(default)           | Description
| relLabel | String ('Relationship') | Label used for nodes describing relationships.
| relNameProp | String ('name') | property name containing the name of the relationship.
| subRelRel | String ('SRO') | relationship type connecting a child relationship to its parent. (Thing are getting pretty meta, right? I hope the examples will help)
| relDir | '<','>' ('') | direction of the relationship. '>' for outgoing, '<' for incoming and default (none) for both.
|===


=== Utility Functions

[options="header"]
|===
| Function Name        | params           | Description
| n10s.rdf.getIRILocalName      | URI string | Returns the local part of the URI (stripping out the namespace)
| n10s.rdf.getIRINamespace      | URI string | Returns the namespace part of the URI (stripping out the local part)
| n10s.rdf.getDataType | string (a property value) | Returns the XMLSchema (or custom) datatype of a property value when present
| n10s.rdf.getLangValue | string (a property value) | Returns the value with the language tag passed as first argument or null if there's not a value for the provided language tag
| n10s.rdf.getLangTag | string (a property value)| Returns the  language tag associated with the property value (when present) and null when no language tag is present.
| n10s.rdf.hasLangTag  a| * String (lang-tag)
* String (a property value)| Returns true if the value has the language tag passed as first argument false if not
| n10s.rdf.getValue | string (a property value)| Returns the value of a datatype of a property after stripping out the datatype information or language tag  when present
| n10s.rdf.shortFormFromFullUri | string (a URI)| Returns the shortened version of an IRI using the existing namespace definitions
| n10s.rdf.fullUriFromShortForm | string (a shortened URI)| Returns the expanded (full) URI given a shortened one created in the load process with `n10s.rdf.import`
|===

//| semantics.importJSONAsTree
//a| * node to link the imported json to
//* the json fragment
//* (optional) relationship name linking the root node of the JSON to the node passed as first param | Imports a JSON payload by mapping it to nodes and relationships (JSON-LD style). Requires a uniqueness constraint on :Resource(uri)


=== Extensions (HTTP endpoints)
[options="header"]
[cols="15,5,45,35"]
|===
| method| type| params| Description
| /rdf/describe/<nodeid or uri>
|GET
a|
* the id of a node or the (urlencoded) uri
* excludeContext: Optional named parameter. If present output will not include connected nodes, just selected one.
* format: RDF serialisation format. When present, it overrides the header param *accept*.
| Produces an RDF serialization of the selected node. The format will be determined by the *accept* parameter in the header. Default is Turtle
|/rdf/describe/find/<l>/<p>/<v>
|GET
a|
* the method takes three parameters passed as path parameters in the URL: <l>/<p>/<v>. They represent respectively a label, a property name and a property value.
* excludeContext: Optional named parameter. If present output will not include connected nodes, just selected one.
* valType: required when the property value is not to be treated as a string. Valid values: INTEGER, FLOAT and BOOLEAN
* format: RDF serialisation format. When present, it overrides the header param *accept*.
| returns  nodes matching the filter on label and property value
| /rdf/cypher
| POST
a| POST request taking as parameter a JSON map with the following keys:

* cypher: the cypher query to run
* cypherParams: parameters  for the cypher query
* showOnlyMapped: (optional, default is false) if present output will exclude unmapped elements (see how to define mappings for labels,attributes, relationships)
* format: RDF serialisation format. When present, it overrides the header param *accept*.
| Produces an RDF serialization of the nodes and relationships returned by the Cypher query
|/rdf/onto
| GET
a| * format: RDF serialisation format. When present, it overrides the header param *accept*.
| returns an OWL ontology based on the graph schema
|===