DBZ-2226 Updates based on comments from Chris

// Metadata created by nebel
//
[id="mysql-connector-events_{context}"]
= MySQL connector events

The {prodname} MySQL connector generates a data change event for each row-level `INSERT`, `UPDATE`, and `DELETE` operation. Each event contains a key and a value. The structure of the key and the value depends on the table that was changed.

{prodname} and Kafka Connect are designed around _continuous streams of event messages_. However, the structure of these events may change over time, which can be difficult for consumers to handle. To address this, each event contains the schema for its content or, if you are using a schema registry, a schema ID that a consumer can use to obtain the schema from the registry. This makes each event self-contained.

The following skeleton JSON shows the basic four parts of a change event. However, how you configure the Kafka Connect converter that you choose to use in your application determines the representation of these four parts in change events. A `schema` field is in a change event only when you configure the converter to produce it. Likewise, the event key and event payload are in a change event only if you configure a converter to produce it. If you use the JSON converver and you configure it to produce all four basic change event parts, change events have this structure:

[source,json,index=0]
----
{
 "schema": { //<1>
   ...
  },
 "payload": { //<2>
   ...
 },
 "schema": { //<3>
   ...
 },
 "payload": { //<4>
   ...
 },
}
----

.Overview of change event basic content
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`schema`
|The first `schema` field is part of the event key. It specifies a Kafka Connect schema that describes what is in the event key's `payload` portion. In other words, the first `schema` field describes the structure of the primary key, or the unique key if the table does not have a primary key, for the table that was changed. +
 +
It is possible to override the table's primary key by setting the {link-prefix}:{link-mysql-connector}#mysql-property-message-key-columns[`message.key.columns` connector configuration property]. In this case, the first schema field describes the structure of the the key identified by that property.

|2
|`payload`
|The first `payload` field is part of the event key. It has the structure described by the previous `schema` field and it contains the key for the row that was changed.

|3
|`schema`
|The second `schema` field is part of the event value. It specifies the Kafka Connect schema that describes what is in the event value's `payload` portion. In other words, the second `schema` describes the structure of the row that was changed. Typically, this schema contains nested schemas.

|4
|`payload`
|The second `payload` field is part of the event value. It has the structure described by the previous `schema` field and it contains the actual data for the row that was changed.

|===

By default, the connector streams change event records to topics with names that are the same as the event's originating table. See {link-prefix}:{link-mysql-connector}#the-mysql-connector-and-kafka-topics_{context}[MySQL connector and Kafka topics].

[WARNING]
====
The MySQL connector ensures that all Kafka Connect schema names adhere to the link:http://avro.apache.org/docs/current/spec.html#names[Avro schema name format]. This means that the logical server name must start with a Latin letter or an underscore, that is, a-z, A-Z, or \_. Each remaining character in the logical server name and each character in the database and table names must be a Latin letter, a digit, or an underscore, that is, a-z, A-Z, 0-9, or \_. If there is an invalid character it is replaced with an underscore character.

This can lead to unexpected conflicts if the logical server name, a database name, or a table name contains invalid characters, and the only characters that distinguish names from one another are invalid and thus replaced with underscores.
====

== Change event keys

A change event's key contains the schema for the changed table's key and the changed row's actual key. Both the schema and its corresponding payload contain a field for each column in the changed table's `PRIMARY KEY` (or unique constraint) at the time the connector created the event.

Consider the following `customers` table, which is followed by an example of a change event key for this table.

.Example table
[source,sql]
----
CREATE TABLE customers (
  id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,
  first_name VARCHAR(255) NOT NULL,
  last_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL UNIQUE KEY
) AUTO_INCREMENT=1001;
----

.Example change event key
Every change event that captures a change to the `customers` table has the same event key schema. For as long as the `customers` table has the previous definition, every change event that captures a change to the `customers` table has the following key structure. In JSON, it looks like this:

[source,json,index=0]
----
{
 "schema": { <1>
    "type": "struct",
    "name": "mysql-server-1.inventory.customers.Key", <2>
    "optional": false, <3>
    "fields": [ <4>
      {
        "field": "id",
        "type": "int32",
        "optional": false
      }
    ]
  },
 "payload": { <5>
    "id": 1001
  }
}
----

.Description of change event key
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`schema`
|The schema portion of the key specifies a Kafka Connect schema that describes what is in the key's `payload` portion.

|2
|`mysql-server-1.inventory.customers.Key`
a|Name of the schema that defines the structure of the key's payload. This schema describes the structure of the primary key for the table that was changed. Key schema names have the format _connector-name_._database-name_._table-name_.`Key`. In this example: +

* `mysql-server-1` is the name of the connector that generated this event. +
* `inventory` is the database that contains the table that was changed. +
* `customers` is the table that was updated.

|3
|`optional`
|Indicates whether the event key must contain a value in its `payload` field. In this example, a value in the key's payload is required. A value in the key's payload field is optional when a table does not have a primary key.

|4
|`fields`
|Specifies each field that is expected in the `payload`, including each field's name, type, and whether it is required.

|5
|`payload`
|Contains the key for the row for which this change event was generated. In this example, the key, contains a single `id` field whose value is `1001`.

|===

== Change event values

The value in a change event is a bit more complicated than the key. Like the key, the value has a `schema` section and a `payload` section. The `schema` section contains the schema that describes the `Envelope` structure of the `payload` section, including its nested fields. Change events for operations that create, update or delete data all have a value payload with an envelope structure.

Consider the same sample table that was used to show an example of a change event key:

[source,sql]
----
CREATE TABLE customers (
  id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,
  first_name VARCHAR(255) NOT NULL,
  last_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL UNIQUE KEY
) AUTO_INCREMENT=1001;
----

The value portion of a change event for a change to this table is described for each event type:

* <<mysql-create-events,_create_ events>>
* <<mysql-update-events,_update_ events>>
* <<mysql-delete-events,_delete_ events>>

[id="mysql-create-events"]
=== _create_ events

The following example shows the value portion of a change event that the connector generates for an operation that creates data in the `customers` table:

[source,json,options="nowrap",subs="+attributes"]
----
{
  "schema": { // <1>
    "type": "struct",
    "fields": [
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "id"
          },
          {
            "type": "string",
            "optional": false,
            "field": "first_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "last_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "email"
          }
        ],
        "optional": true,
        "name": "mysql-server-1.inventory.customers.Value", // <2>
        "field": "before"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "id"
          },
          {
            "type": "string",
            "optional": false,
            "field": "first_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "last_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "email"
          }
        ],
        "optional": true,
        "name": "mysql-server-1.inventory.customers.Value", // <2>
        "field": "after"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "string",
            "optional": false,
            "field": "version"
          },
          {
            "type": "string",
            "optional": false,
            "field": "connector"
          },
          {
            "type": "string",
            "optional": false,
            "field": "name"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "ts_sec"
          },
          {
            "type": "boolean",
            "optional": true,
            "default": false,
            "field": "snapshot"
          },
          {
            "type": "string",
            "optional": false,
            "field": "db"
          },
          {
            "type": "string",
            "optional": true,
            "field": "table"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "server_id"
          },
          {
            "type": "string",
            "optional": true,
            "field": "gtid"
          },
          {
            "type": "string",
            "optional": false,
            "field": "file"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "pos"
          },
          {
            "type": "int32",
            "optional": false,
            "field": "row"
          },
          {
            "type": "int64",
            "optional": true,
            "field": "thread"
          },
          {
            "type": "string",
            "optional": true,
            "field": "query"
          }
        ],
        "optional": false,
        "name": "io.product.connector.mysql.Source", // <2>
        "field": "source"
      },
      {
        "type": "string",
        "optional": false,
        "field": "op"
      },
      {
        "type": "int64",
        "optional": true,
        "field": "ts_ms"
      }
    ],
    "optional": false,
    "name": "mysql-server-1.inventory.customers.Envelope" // <2>
  },
  "payload": { // <3>
    "op": "c", // <4>
    "ts_ms": 1465491411815, // <5>
    "before": null, // <6>
    "after": { // <7>
      "id": 1004,
      "first_name": "Anne",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "source": { // <8>
      "version": "{debezium-version}",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_sec": 0,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 0,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 154,
      "row": 0,
      "thread": 7,
      "query": "INSERT INTO customers (first_name, last_name, email) VALUES ('Anne', 'Kretchmar', 'annek@noanswer.org')"
    }
  }
}
----

.Descriptions of _create_ event value fields
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`schema`
|The value's schema, which describes the structure of the value's payload. A change event's value schema is the same in every change event that the connector generates for a particular table.

|2
|`name`
a|In the `schema` section, each `name` field specifies the schema for a field in the value's payload. In this example:

* `mysql-server-1.inventory.customers.Value` is the schema for the payload's `before` and `after` fields. This schema is specific to the `customers` table.

* `io.product.connector.mysql.Source` is the schema for the payload's `source` field. This schema is specific to the MySQL connector. The connector uses it for all events that it generates.

* `mysql-server-1.inventory.customers.Envelope` is the schema for the overall structure of the payload, where `mysql-server-1` is the connector name, `inventory` is the database, and `customers` is the table.

ifdef::community[]
Names of schemas for `before` and `after` fields are of the form `_logicalName_._tableName_.Value`, which ensures that the schema name is unique in the database. This means that when using the {link-prefix}:{link-avro-serialization}[Avro converter], the resulting Avro schema for each table in each logical source has its own evolution and history.
endif::community[]

|3
|`payload`
|The value's actual data. This is the information that the change event is providing.

It may appear that the JSON representations of the events are much larger than the rows they describe. This is because the JSON representation must include the schema and the payload portions of the message.
However, by using the {link-prefix}:{link-avro-serialization}[Avro converter], you can significantly decrease the size of the messages that the connector streams to Kafka topics.

|4
|`op`
a| Mandatory string that describes the type of operation that caused the connector to generate the event. In this example, `c` indicates that the operation created a row. Valid values are:

* `c` = create
* `u` = update
* `d` = delete
* `r` = read (applies to only snapshots)

|5
|`ts_ms`
a| Optional field that displays the time at which the connector processed the event. The time is based on the system clock in the JVM running the Kafka Connect task.

|6
|`before`
| An optional field that specifies the state of the row before the event occurred. When the `op` field is `c` for create, as it is in this example, the `before` field is `null` since this change event is for new content.

|7
|`after`
| An optional field that specifies the state of the row after the event occurred. In this example, the `after` field contains the values of the new row's `id`, `first_name`, `last_name`, and `email` columns.

|8
|`source`
a| Mandatory field that describes the source metadata for the event. This field contains information that you can use to compare this event with other events, with regard to the origin of the events, the order in which the events occurred, and whether events were part of the same transaction. The source metadata includes:

* {prodname} version
* Connector name
* binlog name where the event was recorded
* binlog position
* Row within the event
* If the event was part of a snapshot
* Name of the database and table that contain the new row
* ID of the MySQL thread that created the event (non-snapshot only)
* MySQL server ID (if available)
* Timestamp

If the {link-prefix}:{link-mysql-connector}#enable-query-log-events-for-cdc_{context}[`binlog_rows_query_log_events`] MySQL configuration option is enabled and the connector configuration `include.query` property is enabled, the `source` field also provides the `query` field, which contains the original SQL statement that caused the change event.

|===

[id="mysql-update-events"]
=== _update_ events

The value of a change event for an update in the sample `customers` table has the same schema as a _create_ event for that table. Likewise, the event value's payload has the same structure. However, the event value payload contains different values in an _update_ event. Here is an example of a change event value in an event that the connector generates for an update in the `customers` table:

[source,json,options="nowrap",subs="+attributes"]
----
{
  "schema": { ... },
  "payload": {
    "before": { // <1>
      "id": 1004,
      "first_name": "Anne",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "after": { // <2>
      "id": 1004,
      "first_name": "Anne Marie",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "source": { // <3>
      "version": "{debezium-version}",
      "name": "mysql-server-1",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_sec": 1465581,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 223344,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 484,
      "row": 0,
      "thread": 7,
      "query": "UPDATE customers SET first_name='Anne Marie' WHERE id=1004"
    },
    "op": "u", // <4>
    "ts_ms": 1465581029523
  }
}
----

.Descriptions of _update_ event value fields
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`before`
|An optional field that specifies the state of the row before the event occurred. In an _update_ event value, the `before` field contains a field for each table column and the value that was in that column before the database commit. In this example, the `first_name` value is `Anne.`

|2
|`after`
| An optional field that specifies the state of the row after the event occurred. You can compare the `before` and `after` structures to determine what the update to this row was. In the example, the `first_name` value is now `Anne Marie`.

|3
|`source`
a|Mandatory field that describes the source metadata for the event. The `source` field structure has the same fields as in a _create_ event, but some values are different, for example, the sample _update_ event is from a different position in the binlog. The source metadata includes:

* {prodname} version
* Connector name
* binlog name where the event was recorded
* binlog position
* Row within the event
* If the event was part of a snapshot
* Name of the database and table that contain the updated row
* ID of the MySQL thread that created the event (non-snapshot only)
* MySQL server ID (if available)
* Timestamp

If the {link-prefix}:{link-mysql-connector}#enable-query-log-events-for-cdc_{context}[`binlog_rows_query_log_events`] MySQL configuration option is enabled and the connector configuration `include.query` property is enabled, the `source` field also provides the `query` field, which contains the original SQL statement that caused the change event.

|4
|`op`
a|Mandatory string that describes the type of operation. In an _update_ event value, the `op` field value is `u`, signifying that this row changed because of an update.

|===

[NOTE]
====
Updating the columns for a row's primary/unique key changes the value of the row's key. When a key changes, {prodname} outputs _three_ events: a `DELETE` event and a {link-prefix}:{link-mysql-connector}#mysql-tombstone-events[tombstone event] with the old key for the row, followed by an event with the new key for the row. Details are in the next section.
====

[id="mysql-primary-key-updates"]
=== Primary key updates

An `UPDATE` operation that changes a row's primary key field(s) is known
as a primary key change. For a primary key change, in place of an `UPDATE` event record, the connector emits a `DELETE` event record for the old key and a `CREATE` event record for the new (updated) key. These events have the usual structure and content, and in addition, each one has a message header related to the primary key change:

* The `DELETE` event record has `__debezium.newkey` as a message header. The value of this header is the new primary key for the updated row.

* The `CREATE` event record has `__debezium.oldkey` as a message header. The value of this header is the previous (old) primary key that the updated row had.

[id="mysql-delete-events"]
=== _delete_ events

The value in a _delete_ change event has the same `schema` portion as _create_ and _update_ events for the same table. The `payload` portion in a _delete_ event for the sample `customers` table looks like this:

[source,json,options="nowrap",subs="+attributes"]
----
{
  "schema": { ... },
  "payload": {
    "before": { // <1>
      "id": 1004,
      "first_name": "Anne Marie",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "after": null, // <2>
    "source": { // <3>
      "version": "{debezium-version}",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_sec": 1465581,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 223344,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 805,
      "row": 0,
      "thread": 7,
      "query": "DELETE FROM customers WHERE id=1004"
    },
    "op": "d", // <4>
    "ts_ms": 1465581902461 // <5>
  }
}
----

.Descriptions of _delete_ event value fields
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`before`
|Optional field that specifies the state of the row before the event occurred. In a _delete_ event value, the `before` field contains the values that were in the row before it was deleted with the database commit.

|2
|`after`
| Optional field that specifies the state of the row after the event occurred. In a _delete_ event value, the `after` field is `null`, signifying that the row no longer exists.

|3
|`source`
a|Mandatory field that describes the source metadata for the event. In a _delete_ event value, the `source` field structure is the same as for _create_ and _update_ events for the same table. Many `source` field values are also the same. In a _delete_ event value, the `ts_ms` and `pos` field values, as well as other values, might have changed. But the `source` field in a _delete_ event value provides the same metadata:

* {prodname} version
* Connector name
* binlog name where the event was recorded
* binlog position
* Row within the event
* If the event was part of a snapshot
* Name of the database and table that contain the updated row
* ID of the MySQL thread that created the event (non-snapshot only)
* MySQL server ID (if available)
* Timestamp

If the {link-prefix}:{link-mysql-connector}#enable-query-log-events-for-cdc_{context}[`binlog_rows_query_log_events`] MySQL configuration option is enabled and the connector configuration `include.query` property is enabled, the `source` field also provides the `query` field, which contains the original SQL statement that caused the change event.

|4
|`op`
a|Mandatory string that describes the type of operation. The `op` field value is `d`, signifying that this row was deleted.

|5
|`ts_ms`
a|Optional field that displays the time at which the connector processed the event. The time is based on the system clock in the JVM running the Kafka Connect task.

|===

A _delete_ change event record provides a consumer with the information it needs to process the removal of this row. The old values are included because some consumers might require them in order to properly handle the removal.

MySQL connector events are designed to work with link:{link-kafka-docs}/#compaction[Kafka log compaction]. Log compaction enables removal of some older messages as long as at least the most recent message for every key is kept. This lets Kafka reclaim storage space while ensuring that the topic contains a complete data set and can be used for reloading key-based state.

[id="mysql-tombstone-events"]
.Tombstone events
When a row is deleted, the _delete_ event value still works with log compaction, because Kafka can remove all earlier messages that have that same key. However, for Kafka to remove all messages that have that same key, the message value must be `null`. To make this possible, after {prodname}’s MySQL connector emits a _delete_ event, the connector emits a special tombstone event that has the same key but a `null` value.

// Metadata created by nebel
//
[id="mysql-connector-events_{context}"]
= MySQL connector events

The {prodname} MySQL connector generates a data change event for each row-level `INSERT`, `UPDATE`, and `DELETE` operation. Each event contains a key and a value. The structure of the key and the value depends on the table that was changed.

{prodname} and Kafka Connect are designed around _continuous streams of event messages_. However, the structure of these events may change over time, which can be difficult for consumers to handle. To address this, each event contains the schema for its content or, if you are using a schema registry, a schema ID that a consumer can use to obtain the schema from the registry. This makes each event self-contained.

The following skeleton JSON shows the basic four parts of a change event. However, how you configure the Kafka Connect converter that you choose to use in your application determines the representation of these four parts in change events. A `schema` field is in a change event only when you configure the converter to produce it. Likewise, the event key and event payload are in a change event only if you configure a converter to produce it. If you use the JSON converver and you configure it to produce all four basic change event parts, change events have this structure:

[source,json,index=0]
----
{
 "schema": { //<1>
   ...
  },
 "payload": { //<2>
   ...
 },
 "schema": { //<3>
   ...
 },
 "payload": { //<4>
   ...
 },
}
----

.Overview of change event basic content
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`schema`
|The first `schema` field is part of the event key. It specifies a Kafka Connect schema that describes what is in the event key's `payload` portion. In other words, the first `schema` field describes the structure of the primary key, or the unique key if the table does not have a primary key, for the table that was changed.

Rarely, converter configuration overrides the key column with some other structure. In this case, the first schema field describes that structure.

|2
|`payload`
|The first `payload` field is part of the event key. It has the structure described by the previous `schema` field and it contains the key for the row that was changed.

|3
|`schema`
|The second `schema` field is part of the event value. It specifies the Kafka Connect schema that describes what is in the event value's `payload` portion. In other words, the second `schema` describes the structure of the row that was changed. Typically, this schema contains nested schemas.

|4
|`payload`
|The second `payload` field is part of the event value. It has the structure described by the previous `schema` field and it contains the actual data for the row that was changed.

|===

By default, the connector streams change event records to topics with names that are the same as the event's originating table. See {link-prefix}:{link-mysql-connector}#the-mysql-connector-and-kafka-topics_{context}[MySQL connector and Kafka topics].

[WARNING]
====
The MySQL connector ensures that all Kafka Connect schema names adhere to the link:http://avro.apache.org/docs/current/spec.html#names[Avro schema name format]. This means that the logical server name must start with a Latin letter or an underscore, that is, a-z, A-Z, or \_. Each remaining character in the logical server name and each character in the database and table names must be a Latin letter, a digit, or an underscore, that is, a-z, A-Z, 0-9, or \_. If there is an invalid character it is replaced with an underscore character.

This can lead to unexpected conflicts if the logical server name, a database name, or a table name contains invalid characters, and the only characters that distinguish names from one another are invalid and thus replaced with underscores.
====

== Change event keys

A change event's key contains the schema for the changed table's key and the changed row's actual key. Both the schema and its corresponding payload contain a field for each column in the changed table's `PRIMARY KEY` (or unique constraint) at the time the connector created the event.

Consider the following `customers` table, which is followed by an example of a change event key for this table.

.Example table
[source,sql]
----
CREATE TABLE customers (
  id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,
  first_name VARCHAR(255) NOT NULL,
  last_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL UNIQUE KEY
) AUTO_INCREMENT=1001;
----

.Example change event key
Every change event that captures a change to the `customers` table has the same event key schema. For as long as the `customers` table has the previous definition, every change event that captures a change to the `customers` table has the following key structure. In JSON, it looks like this:

[source,json,index=0]
----
{
 "schema": { <1>
    "type": "struct",
    "name": "mysql-server-1.inventory.customers.Key", <2>
    "optional": false, <3>
    "fields": [ <4>
      {
        "field": "id",
        "type": "int32",
        "optional": false
      }
    ]
  },
 "payload": { <5>
    "id": 1001
  }
}
----

.Description of change event key
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`schema`
|The schema portion of the key specifies a Kafka Connect schema that describes what is in the key's `payload` portion.

|2
|`mysql-server-1.inventory.customers.Key`
a|Name of the schema that defines the structure of the key's payload. This schema describes the structure of the primary key for the table that was changed. Key schema names have the format _connector-name_._database-name_._table-name_.`Key`. In this example: +

* `mysql-server-1` is the name of the connector that generated this event. +
* `inventory` is the database that contains the table that was changed. +
* `customers` is the table that was updated.

|3
|`optional`
|Indicates whether the event key must contain a value in its `payload` field. In this example, a value in the key's payload is required. A value in the key's payload field is optional when a table does not have a primary key.

|4
|`fields`
|Specifies each field that is expected in the `payload`, including each field's name, type, and whether it is required.

|5
|`payload`
|Contains the key for the row for which this change event was generated. In this example, the key, contains a single `id` field whose value is `1001`.

|===

== Change event values

The value in a change event is a bit more complicated than the key. Like the key, the value has a `schema` section and a `payload` section. The `schema` section contains the schema that describes the `Envelope` structure of the `payload` section, including its nested fields. Change events for operations that create, update or delete data all have a value payload with an envelope structure.

Consider the same sample table that was used to show an example of a change event key:

[source,sql]
----
CREATE TABLE customers (
  id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,
  first_name VARCHAR(255) NOT NULL,
  last_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL UNIQUE KEY
) AUTO_INCREMENT=1001;
----

The value portion of a change event for a change to this table is described for each event type:

* <<mysql-create-events,_create_ events>>
* <<mysql-update-events,_update_ events>>
* <<mysql-delete-events,_delete_ events>>

[id="mysql-create-events"]
=== _create_ events

The following example shows the value portion of a change event that the connector generates for an operation that creates data in the `customers` table:

[source,json,options="nowrap",subs="+attributes"]
----
{
  "schema": { // <1>
    "type": "struct",
    "fields": [
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "id"
          },
          {
            "type": "string",
            "optional": false,
            "field": "first_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "last_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "email"
          }
        ],
        "optional": true,
        "name": "mysql-server-1.inventory.customers.Value", // <2>
        "field": "before"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "id"
          },
          {
            "type": "string",
            "optional": false,
            "field": "first_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "last_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "email"
          }
        ],
        "optional": true,
        "name": "mysql-server-1.inventory.customers.Value", // <2>
        "field": "after"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "string",
            "optional": false,
            "field": "version"
          },
          {
            "type": "string",
            "optional": false,
            "field": "connector"
          },
          {
            "type": "string",
            "optional": false,
            "field": "name"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "ts_ms"
          },
          {
            "type": "boolean",
            "optional": true,
            "default": false,
            "field": "snapshot"
          },
          {
            "type": "string",
            "optional": false,
            "field": "db"
          },
          {
            "type": "string",
            "optional": true,
            "field": "table"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "server_id"
          },
          {
            "type": "string",
            "optional": true,
            "field": "gtid"
          },
          {
            "type": "string",
            "optional": false,
            "field": "file"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "pos"
          },
          {
            "type": "int32",
            "optional": false,
            "field": "row"
          },
          {
            "type": "int64",
            "optional": true,
            "field": "thread"
          },
          {
            "type": "string",
            "optional": true,
            "field": "query"
          }
        ],
        "optional": false,
        "name": "io.product.connector.mysql.Source", // <2>
        "field": "source"
      },
      {
        "type": "string",
        "optional": false,
        "field": "op"
      },
      {
        "type": "int64",
        "optional": true,
        "field": "ts_ms"
      }
    ],
    "optional": false,
    "name": "mysql-server-1.inventory.customers.Envelope" // <2>
  },
  "payload": { // <3>
    "op": "c", // <4>
    "ts_ms": 1465491411815, // <5>
    "before": null, // <6>
    "after": { // <7>
      "id": 1004,
      "first_name": "Anne",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "source": { // <8>
      "version": "{debezium-version}",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_ms": 0,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 0,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 154,
      "row": 0,
      "thread": 7,
      "query": "INSERT INTO customers (first_name, last_name, email) VALUES ('Anne', 'Kretchmar', 'annek@noanswer.org')"
    }
  }
}
----

.Descriptions of _create_ event value fields
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`schema`
|The value's schema, which describes the structure of the value's payload. A change event's value schema is the same in every change event that the connector generates for a particular table.

|2
|`name`
a|In the `schema` section, each `name` field specifies the schema for a field in the value's payload. In this example:

* `mysql-server-1.inventory.customers.Value` is the schema for the payload's `before` and `after` fields. This schema is specific to the `customers` table.

* `io.product.connector.mysql.Source` is the schema for the payload's `source` field. This schema is specific to the MySQL connector. The connector uses it for all events that it generates.

* `mysql-server-1.inventory.customers.Envelope` is the schema for the overall structure of the payload, where `mysql-server-1` is the connector name, `inventory` is the database, and `customers` is the table.

ifdef::community[]
Names of schemas for `before` and `after` fields are of the form `_logicalName_._tableName_.Value`, which ensures that the schema name is unique in the database. This means that when using the {link-prefix}:{link-avro-serialization}[Avro converter], the resulting Avro schema for each table in each logical source has its own evolution and history.
endif::community[]

|3
|`payload`
|The value's actual data. This is the information that the change event is providing.

It may appear that the JSON representations of the events are much larger than the rows they describe. This is because the JSON representation must include the schema and the payload portions of the message.
However, by using the {link-prefix}:{link-avro-serialization}[Avro converter], you can significantly decrease the size of the messages that the connector streams to Kafka topics.

|4
|`op`
a| Mandatory string that describes the type of operation that caused the connector to generate the event. In this example, `c` indicates that the operation created a row. Valid values are:

* `c` = create
* `u` = update
* `d` = delete
* `r` = read (applies to only snapshots)

|5
|`ts_ms`
a| Optional field that displays the time at which the connector processed the event. The time is based on the system clock in the JVM running the Kafka Connect task.

|6
|`before`
| An optional field that specifies the state of the row before the event occurred. When the `op` field is `c` for create, as it is in this example, the `before` field is `null` since this change event is for new content.

|7
|`after`
| An optional field that specifies the state of the row after the event occurred. In this example, the `after` field contains the values of the new row's `id`, `first_name`, `last_name`, and `email` columns.

|8
|`source`
a| Mandatory field that describes the source metadata for the event. The `source` structure shows MySQL information about this change, which provides traceability. It also has information you can use to compare to other events in this and other topics to know whether this event occurred before, after, or as part of the same MySQL commit as other events. The source metadata includes:

* {prodname} version
* Connector name
* binlog name where the event was recorded
* binlog position
* Row within the event
* If the event was part of a snapshot
* Name of the database and table that contain the new row
* ID of the MySQL thread that created the event (non-snapshot only)
* MySQL server ID (if available)
* Timestamp

If the {link-prefix}:{link-mysql-connector}#enable-query-log-events-for-cdc_{context}[`binlog_rows_query_log_events`] MySQL configuration option is enabled and the connector configuration `include.query` property is enabled, the `source` field also provides the `query` field, which contains the original SQL statement that caused the change event.

|===

[id="mysql-update-events"]
=== _update_ events

The value of a change event for an update in the sample `customers` table has the same schema as a _create_ event for that table. Likewise, the event value's payload has the same structure. However, the event value payload contains different values in an _update_ event. Here is an example of a change event value in an event that the connector generates for an update in the `customers` table:

[source,json,options="nowrap",subs="+attributes"]
----
{
  "schema": { ... },
  "payload": {
    "before": { // <1>
      "id": 1004,
      "first_name": "Anne",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "after": { // <2>
      "id": 1004,
      "first_name": "Anne Marie",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "source": { // <3>
      "version": "{debezium-version}",
      "name": "mysql-server-1",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_ms": 1465581,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 223344,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 484,
      "row": 0,
      "thread": 7,
      "query": "UPDATE customers SET first_name='Anne Marie' WHERE id=1004"
    },
    "op": "u", // <4>
    "ts_ms": 1465581029523
  }
}
----

.Descriptions of _update_ event value fields
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`before`
|An optional field that specifies the state of the row before the event occurred. In an _update_ event value, the `before` field contains a field for each table column and the value that was in that column before the database commit. In this example, the `first_name` value is `Anne.`

|2
|`after`
| An optional field that specifies the state of the row after the event occurred. You can compare the `before` and `after` structures to determine what the update to this row was. In the example, the `first_name` value is now `Anne Marie`.

|3
|`source`
a|Mandatory field that describes the source metadata for the event. The `source` field structure has the same fields as in a _create_ event, but some values are different, for example, the sample _update_ event is from a different position in the binlog. The source metadata includes:

* {prodname} version
* Connector name
* binlog name where the event was recorded
* binlog position
* Row within the event
* If the event was part of a snapshot
* Name of the database and table that contain the updated row
* ID of the MySQL thread that created the event (non-snapshot only)
* MySQL server ID (if available)
* Timestamp

If the {link-prefix}:{link-mysql-connector}#enable-query-log-events-for-cdc_{context}[`binlog_rows_query_log_events`] MySQL configuration option is enabled and the connector configuration `include.query` property is enabled, the `source` field also provides the `query` field, which contains the original SQL statement that caused the change event.

|4
|`op`
a|Mandatory string that describes the type of operation. In an _update_ event value, the `op` field value is `u`, signifying that this row changed because of an update.

|===

[NOTE]
====
Updating the columns for a row's primary/unique key changes the value of the row's key. When a key changes, {prodname} outputs _three_ events: a `DELETE` event and a {link-prefix}:{link-mysql-connector}#mysql-tombstone-events[tombstone event] with the old key for the row, followed by an event with the new key for the row. Details are in the next section.
====

[id="mysql-primary-key-updates"]
=== Primary key updates

An `UPDATE` operation that changes a row's primary key field(s) is known
as a primary key change. For a primary key change, in place of an `UPDATE` event record, the connector emits a `DELETE` event record for the old key and a `CREATE` event record for the new (updated) key. These events have the usual structure and content, and in addition, each one has a message header related to the primary key change:

* The `DELETE` event record has `__debezium.newkey` as a message header. The value of this header is the new primary key for the updated row.

* The `CREATE` event record has `__debezium.oldkey` as a message header. The value of this header is the previous (old) primary key that the updated row had.

[id="mysql-delete-events"]
=== _delete_ events

The value in a _delete_ change event has the same `schema` portion as _create_ and _update_ events for the same table. The `payload` portion in a _delete_ event for the sample `customers` table looks like this:

[source,json,options="nowrap",subs="+attributes"]
----
{
  "schema": { ... },
  "payload": {
    "before": { // <1>
      "id": 1004,
      "first_name": "Anne Marie",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "after": null, // <2>
    "source": { // <3>
      "version": "{debezium-version}",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_ms": 1465581,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 223344,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 805,
      "row": 0,
      "thread": 7,
      "query": "DELETE FROM customers WHERE id=1004"
    },
    "op": "d", // <4>
    "ts_ms": 1465581902461 // <5>
  }
}
----

.Descriptions of _delete_ event value fields
[cols="1,2,7",options="header"]
|===
|Item |Field name |Description

|1
|`before`
|Optional field that specifies the state of the row before the event occurred. In a _delete_ event value, the `before` field contains the values that were in the row before it was deleted with the database commit.

|2
|`after`
| Optional field that specifies the state of the row after the event occurred. In a _delete_ event value, the `after` field is `null`, signifying that the row no longer exists.

|3
|`source`
a|Mandatory field that describes the source metadata for the event. In a _delete_ event value, the `source` field structure is the same as for _create_ and _update_ events for the same table. Many `source` field values are also the same. In a _delete_ event value, the `ts_ms` and `pos` field values, as well as other values, might have changed. But the `source` field in a _delete_ event value provides the same metadata:

* {prodname} version
* Connector name
* binlog name where the event was recorded
* binlog position
* Row within the event
* If the event was part of a snapshot
* Name of the database and table that contain the updated row
* ID of the MySQL thread that created the event (non-snapshot only)
* MySQL server ID (if available)
* Timestamp

If the {link-prefix}:{link-mysql-connector}#enable-query-log-events-for-cdc_{context}[`binlog_rows_query_log_events`] MySQL configuration option is enabled and the connector configuration `include.query` property is enabled, the `source` field also provides the `query` field, which contains the original SQL statement that caused the change event.

|4
|`op`
a|Mandatory string that describes the type of operation. The `op` field value is `d`, signifying that this row was deleted.

|5
|`ts_ms`
a|Optional field that displays the time at which the connector processed the event. The time is based on the system clock in the JVM running the Kafka Connect task.

|===

A _delete_ change event record provides a consumer with the information it needs to process the removal of this row. The old values are included because some consumers might require them in order to properly handle the removal.

MySQL connector events are designed to work with link:{link-kafka-docs}/#compaction[Kafka log compaction]. Log compaction enables removal of some older messages as long as at least the most recent message for every key is kept. This lets Kafka reclaim storage space while ensuring that the topic contains a complete data set and can be used for reloading key-based state.

[id="mysql-tombstone-events"]
.Tombstone events
When a row is deleted, the _delete_ event value still works with log compaction, because Kafka can remove all earlier messages that have that same key. However, for Kafka to remove all messages that have that same key, the message value must be `null`. To make this possible, after {prodname}’s MySQL connector emits a _delete_ event, the connector emits a special tombstone event that has the same key but a `null` value.


Release version 3.5.0.5

Release version 3.5.0.5

:readme:
:branch: 3.5
:docs: https://neo4j.com/docs/labs/apoc/current
:apoc-release: 3.5.0.5
:neo4j-version: 3.5.11
:img: https://raw.githubusercontent.com/neo4j-contrib/neo4j-apoc-procedures/{branch}/docs/images

= Awesome Procedures for Neo4j {branch}.x

// tag::readme[]

== Introduction

// tag::intro[]
image::{img}/apoc.gif[float=right]

// tag::intro-text[]
Neo4j 3.x introduced the concept of user-defined procedures and functions.
Those are custom implementations of certain functionality, that can't be (easily) expressed in Cypher itself.
They are implemented in Java and can be easily deployed into your Neo4j instance, and then be called from Cypher directly.

The APOC library consists of many (about 450) procedures and functions to help with many different tasks in areas like data integration, graph algorithms or data conversion.
// end::intro-text[]

=== License

Apache License 2.0

// tag::name-history[]
=== "APOC" Name history

// tag::name-history-text[]
http://matrix.wikia.com/wiki/Apoc[Apoc^] was the technician and driver on board of the Nebuchadnezzar in the Matrix movie. He was killed by Cypher.

*APOC* was also the first bundled http://neo4j.com/blog/convenient-package-neo4j-apoc-0-1-released/[A Package Of Component^] for Neo4j in 2009.

*APOC* also stands for "Awesome Procedures On Cypher"
// end::name-history-text[]
// end::name-history[]

// tag::install-desktop[]
== Installation: With Neo4j Desktop

APOC is easily installed with http://neo4j.com/download[Neo4j Desktop], after creating your database just go to the "Manage" screen and the "Plugins" tab.
Then click "Install" in the APOC box and you're done.

// end::install-desktop[]
image::{img}/desktop-apoc.jpg[width=800]

== Feedback

// tag::feedback[]
Please provide feedback and report bugs as https://github.com/neo4j-contrib/neo4j-apoc-procedures/issues[GitHub issues] or join the https://community.neo4j.com/c/neo4j-graph-platform/procedures-apoc[Neo4j Community Forum and ask in the APOC & Procedures category^].
// end::feedback[]

// tag::calling-procedures[]

== Calling Procedures & Functions within Cypher

// tag::usage[]
User defined *Functions* can be used in *any* expression or predicate, just like built-in functions.

*Procedures* can be called stand-alone with `CALL procedure.name();`

But you can also integrate them into your Cypher statements which makes them so much more powerful.

.Load JSON example
[source,cypher]
----
WITH 'https://raw.githubusercontent.com/neo4j-contrib/neo4j-apoc-procedures/{branch}/src/test/resources/person.json' AS url

CALL apoc.load.json(url) YIELD value as person

MERGE (p:Person {name:person.name})
   ON CREATE SET p.age = person.age, p.children = size(person.children)
----
// end::usage[]
// end::calling-procedures[]

// end::intro[]

== APOC Procedures & Functions Overview

All included procedures are listed in the link:{docs}/overview[overview in the documentation^] and detailed in subsequent sections.

=== Built in Help

// tag::help[]
image::{img}/apoc-help-apoc.jpg[width=600]

[cols="1m,5"]
|===
| call apoc.help('keyword') | lists name, description, signature, roles, based on keyword
|===

// end::help[]

== Detailed Feature Documentation

See the link:{docs}[APOC User Guide^] for documentation of each of the major features of the library, including data import/export, graph refactoring, data conversion, and more.

// tag::signature[]

== Procedure & Function Signatures

To call procedures correctly, you need to know their parameter names, types and positions.
And for YIELDing their results, you have to know the output column names and types.

INFO:The signatures are shown in error messages, if you use a procedure incorrectly.

You can see the procedures signature in the output of `CALL apoc.help("name")`

[source,cypher]
----
CALL apoc.help("dijkstra")
----

The signature is always `name : : TYPE`, so in this case:

----
apoc.algo.dijkstra
 (startNode :: NODE?, endNode :: NODE?,
   relationshipTypesAndDirections :: STRING?, weightPropertyName :: STRING?)
:: (path :: PATH?, weight :: FLOAT?)
----

.Parameter Explanation
[opts=header,cols="m,m"]
|===
| Name | Type
h| Procedure Parameters |
| startNode | Node
| endNode | Node
| relationshipTypesAndDirections | String
| weightPropertyName | String
h| Output Return Columns |
| path  |  Path
| weight | Float
|===

// end::signature[]

// tag::install[]

== Manual Installation: Download latest release

Since APOC relies in some places on Neo4j's internal APIs you need to use the *matching APOC version* for your Neo4j installaton.
Make sure that the *first two version numbers match between Neo4j and APOC*.

Go to http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/{apoc-release}[the latest release] for *Neo4j version {branch}* and download the binary jar to place into your `$NEO4J_HOME/plugins` folder.

You can find http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/[all releases here].

// end::install[]

== Manual Configuration

// tag::warnings[]

[WARNING]
====
Procedures that use internal APIs have to be allowed in `$NEO4J_HOME/conf/neo4j.conf` with, e.g. `+dbms.security.procedures.unrestricted=apoc.*+` for security reasons.

If you want to use this via docker, you need to amend `+-e NEO4J_dbms_security_procedures_unrestricted=apoc.\\\*+` to your `docker run ...` command.
The three backslashes are necessary to prevent wildcard expansions.

You _can_ also whitelist procedures and functions in general to be loaded using: `+dbms.security.procedures.whitelist=apoc.coll.*,apoc.load.*+`
====

// end::warnings[]

// tag::version-matrix[]
=== Version Compatibility Matrix

Since APOC relies in some places on Neo4j's internal APIs you need to use the right APOC version for your Neo4j installaton.

APOC uses a consistent versioning scheme: `<neo4j-version>.<apoc>` version.
The trailing `<apoc>` part of the version number will be incremented with every apoc release.

[opts=header]
|===
|apoc version | neo4j version
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.5.0.5[3.5.0.5^] | 3.5.11 (3.5.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.4.0.4[3.4.0.6^] | 3.4.12 (3.4.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.3.0.4[3.3.0.4^] | 3.3.6 (3.3.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.3.6[3.2.3.6^] | 3.2.9 (3.2.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.9[3.1.3.9^] | 3.1.7 (3.1.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.0.8.6[3.0.8.6^] | 3.0.5-3.0.9 (3.0.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.5.0.0[3.5.0.0^] | 3.5.0-beta01
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.4.0.2[3.4.0.2^] | 3.4.5
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.3.0.3[3.3.0.3^] | 3.3.5
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.3.5[3.2.3.5^] | 3.2.3
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.8[3.1.3.8^] | 3.1.5
|===

// end::version-matrix[]
=== Get APOC Version

To know your current `apoc` version you can use the *function* :

[source,cypher]
----
RETURN apoc.version();
----

// tag::docker[]

=== Using APOC with the Neo4j Docker image

The https://hub.docker.com/_/neo4j/[Neo4j Docker image] allows to supply a volume for the `/plugins` folder.
Download the APOC release matching your Neo4j version to local folder `plugins` and provide it as a data volume:

[source,bash,subs=attributes]
----
mkdir plugins
pushd plugins
wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/{apoc-release}/apoc-{apoc-release}-all.jar
popd
docker run --rm -e NEO4J_AUTH=none -p 7474:7474 -v $PWD/plugins:/plugins -p 7687:7687 neo4j:{branch}
----

If you want to pass custom apoc config to your Docker instance, you can use environment variables, like here:

----
docker run \
    -p 7474:7474 -p 7687:7687 \
    -v $PWD/data:/data -v $PWD/plugins:/plugins \
    --name neo4j-apoc \
    -e NEO4J_apoc_export_file_enabled=true \
    -e NEO4J_apoc_import_file_enabled=true \
    -e NEO4J_apoc_import_file_use__neo4j__config=true \
    neo4j
----

====
If you want to allow APOC's procedures that use internal APIs, you need to amend `+-e NEO4J_dbms_security_procedures_unrestricted=apoc.\\\*+` to your `docker run ...` command.
The three backslashes are necessary to prevent wildcard expansions.
====

// end::docker[]
// tag::build[]

=== Build & install the current development branch from source

----
git clone http://github.com/neo4j-contrib/neo4j-apoc-procedures
cd neo4j-apoc-procedures
./gradlew shadow
cp build/libs/apoc-<version>-all.jar $NEO4J_HOME/plugins/
$NEO4J_HOME/bin/neo4j restart
----

// If you want to run embedded or use neo4j-shell on a disk store, configure your `plugins` directory in `conf/neo4j.conf` with `dbms.plugin.directory=path/to/plugins`.

A full build including running the tests can be run by `./gradlew build`.

// end::build[]

:readme:
:branch: 3.5
:docs: https://neo4j.com/docs/labs/apoc/current
:apoc-release: 3.5.0.4
:neo4j-version: 3.5.6
:img: https://raw.githubusercontent.com/neo4j-contrib/neo4j-apoc-procedures/{branch}/docs/images

= Awesome Procedures for Neo4j {branch}.x

// tag::readme[]

== Introduction

// tag::intro[]
image::{img}/apoc.gif[float=right]

// tag::intro-text[]
Neo4j 3.x introduced the concept of user-defined procedures and functions.
Those are custom implementations of certain functionality, that can't be (easily) expressed in Cypher itself.
They are implemented in Java and can be easily deployed into your Neo4j instance, and then be called from Cypher directly.

The APOC library consists of many (about 450) procedures and functions to help with many different tasks in areas like data integration, graph algorithms or data conversion.
// end::intro-text[]

=== License

Apache License 2.0

// tag::name-history[]
=== "APOC" Name history

// tag::name-history-text[]
http://matrix.wikia.com/wiki/Apoc[Apoc^] was the technician and driver on board of the Nebuchadnezzar in the Matrix movie. He was killed by Cypher.

*APOC* was also the first bundled http://neo4j.com/blog/convenient-package-neo4j-apoc-0-1-released/[A Package Of Component^] for Neo4j in 2009.

*APOC* also stands for "Awesome Procedures On Cypher"
// end::name-history-text[]
// end::name-history[]

// tag::install-desktop[]
== Installation: With Neo4j Desktop

APOC is easily installed with http://neo4j.com/download[Neo4j Desktop], after creating your database just go to the "Manage" screen and the "Plugins" tab.
Then click "Install" in the APOC box and you're done.

// end::install-desktop[]
image::{img}/desktop-apoc.jpg[width=800]

== Feedback

// tag::feedback[]
Please provide feedback and report bugs as https://github.com/neo4j-contrib/neo4j-apoc-procedures/issues[GitHub issues] or join the https://community.neo4j.com/c/neo4j-graph-platform/procedures-apoc[Neo4j Community Forum and ask in the APOC & Procedures category^].
// end::feedback[]

// tag::calling-procedures[]

== Calling Procedures & Functions within Cypher

// tag::usage[]
User defined *Functions* can be used in *any* expression or predicate, just like built-in functions.

*Procedures* can be called stand-alone with `CALL procedure.name();`

But you can also integrate them into your Cypher statements which makes them so much more powerful.

.Load JSON example
[source,cypher]
----
WITH 'https://raw.githubusercontent.com/neo4j-contrib/neo4j-apoc-procedures/{branch}/src/test/resources/person.json' AS url

CALL apoc.load.json(url) YIELD value as person

MERGE (p:Person {name:person.name})
   ON CREATE SET p.age = person.age, p.children = size(person.children)
----
// end::usage[]
// end::calling-procedures[]

// end::intro[]

== APOC Procedures & Functions Overview

All included procedures are listed in the link:{docs}/overview[overview in the documentation^] and detailed in subsequent sections.

=== Built in Help

// tag::help[]
image::{img}/apoc-help-apoc.jpg[width=600]

[cols="1m,5"]
|===
| call apoc.help('keyword') | lists name, description, signature, roles, based on keyword
|===

// end::help[]

== Detailed Feature Documentation

See the link:{docs}[APOC User Guide^] for documentation of each of the major features of the library, including data import/export, graph refactoring, data conversion, and more.

// tag::signature[]

== Procedure & Function Signatures

To call procedures correctly, you need to know their parameter names, types and positions.
And for YIELDing their results, you have to know the output column names and types.

INFO:The signatures are shown in error messages, if you use a procedure incorrectly.

You can see the procedures signature in the output of `CALL apoc.help("name")`

[source,cypher]
----
CALL apoc.help("dijkstra")
----

The signature is always `name : : TYPE`, so in this case:

----
apoc.algo.dijkstra
 (startNode :: NODE?, endNode :: NODE?,
   relationshipTypesAndDirections :: STRING?, weightPropertyName :: STRING?)
:: (path :: PATH?, weight :: FLOAT?)
----

.Parameter Explanation
[opts=header,cols="m,m"]
|===
| Name | Type
h| Procedure Parameters |
| startNode | Node
| endNode | Node
| relationshipTypesAndDirections | String
| weightPropertyName | String
h| Output Return Columns |
| path  |  Path
| weight | Float
|===

// end::signature[]

// tag::install[]

== Manual Installation: Download latest release

Since APOC relies in some places on Neo4j's internal APIs you need to use the *matching APOC version* for your Neo4j installaton.
Make sure that the *first two version numbers match between Neo4j and APOC*.

Go to http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/{apoc-release}[the latest release] for *Neo4j version {branch}* and download the binary jar to place into your `$NEO4J_HOME/plugins` folder.

You can find http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/[all releases here].

// end::install[]

== Manual Configuration

// tag::warnings[]

[WARNING]
====
Procedures that use internal APIs have to be allowed in `$NEO4J_HOME/conf/neo4j.conf` with, e.g. `+dbms.security.procedures.unrestricted=apoc.*+` for security reasons.

If you want to use this via docker, you need to amend `+-e NEO4J_dbms_security_procedures_unrestricted=apoc.\\\*+` to your `docker run ...` command.
The three backslashes are necessary to prevent wildcard expansions.

You _can_ also whitelist procedures and functions in general to be loaded using: `+dbms.security.procedures.whitelist=apoc.coll.*,apoc.load.*+`
====

// end::warnings[]

// tag::version-matrix[]
=== Version Compatibility Matrix

Since APOC relies in some places on Neo4j's internal APIs you need to use the right APOC version for your Neo4j installaton.

APOC uses a consistent versioning scheme: `<neo4j-version>.<apoc>` version.
The trailing `<apoc>` part of the version number will be incremented with every apoc release.

[opts=header]
|===
|apoc version | neo4j version
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.5.0.4[3.5.0.4^] | 3.5.6 (3.5.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.4.0.4[3.4.0.6^] | 3.4.12 (3.4.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.3.0.4[3.3.0.4^] | 3.3.6 (3.3.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.3.6[3.2.3.6^] | 3.2.9 (3.2.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.9[3.1.3.9^] | 3.1.7 (3.1.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.0.8.6[3.0.8.6^] | 3.0.5-3.0.9 (3.0.x)
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.5.0.0[3.5.0.0^] | 3.5.0-beta01
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.4.0.2[3.4.0.2^] | 3.4.5
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.3.0.3[3.3.0.3^] | 3.3.5
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.2.3.5[3.2.3.5^] | 3.2.3
| http://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/3.1.3.8[3.1.3.8^] | 3.1.5
|===

// end::version-matrix[]
=== Get APOC Version

To know your current `apoc` version you can use the *function* :

[source,cypher]
----
RETURN apoc.version();
----

// tag::docker[]

=== Using APOC with the Neo4j Docker image

The https://hub.docker.com/_/neo4j/[Neo4j Docker image] allows to supply a volume for the `/plugins` folder.
Download the APOC release matching your Neo4j version to local folder `plugins` and provide it as a data volume:

[source,bash,subs=attributes]
----
mkdir plugins
pushd plugins
wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/{apoc-release}/apoc-{apoc-release}-all.jar
popd
docker run --rm -e NEO4J_AUTH=none -p 7474:7474 -v $PWD/plugins:/plugins -p 7687:7687 neo4j:{branch}
----

If you want to pass custom apoc config to your Docker instance, you can use environment variables, like here:

----
docker run \
    -p 7474:7474 -p 7687:7687 \
    -v $PWD/data:/data -v $PWD/plugins:/plugins \
    --name neo4j-apoc \
    -e NEO4J_apoc_export_file_enabled=true \
    -e NEO4J_apoc_import_file_enabled=true \
    -e NEO4J_apoc_import_file_use__neo4j__config=true \
    neo4j
----

====
If you want to allow APOC's procedures that use internal APIs, you need to amend `+-e NEO4J_dbms_security_procedures_unrestricted=apoc.\\\*+` to your `docker run ...` command.
The three backslashes are necessary to prevent wildcard expansions.
====

// end::docker[]
// tag::build[]

=== Build & install the current development branch from source

----
git clone http://github.com/neo4j-contrib/neo4j-apoc-procedures
cd neo4j-apoc-procedures
./gradlew shadow
cp build/libs/apoc-<version>-all.jar $NEO4J_HOME/plugins/
$NEO4J_HOME/bin/neo4j restart
----

// If you want to run embedded or use neo4j-shell on a disk store, configure your `plugins` directory in `conf/neo4j.conf` with `dbms.plugin.directory=path/to/plugins`.

A full build including running the tests can be run by `./gradlew build`.

// end::build[]