<commit_before># Kuzzle WebSocket API Specifications

## Introduction

You can connect your application directly to Kuzzle, using WebSockets.

This will give you a direct access to the Kuzzle's router controller, dispatching your queries to the right components, which in turn will send you back a ``response``


## Index

* [How to connect to Kuzzle](#how-to-connect-to-kuzzle)
* [What are responses objects](#what-are-responses-objects)
* [Performing queries](#performing-queries)
  * [Subscribing to documents](#subscribing-to-documents)
    * [Notifications you can receive](#notifications)
  * [Counting the number of subscriptions on a given room](#counting-the-number-of-subscriptions-on-a-given-room)
  * [Unsubscribing of a room](#unsubscribing-of-a-room)
  * [Sending a publish/subscribe message](#sending-a-publish-subscribe-message)
  * [Creating a new document](#creating-a-new-document)
  * [Retrieving a document](#retrieving-a-document)
  * [Searching for documents](#searching-for-documents)
  * [Updating a document](#updating-a-document)
  * [Counting documents](#counting-documents)
  * [Deleting a document using a document unique ID](#deleting-a-document-using-a-document-unique-id)
  * [Deleting documents using a query](#deleting-documents-using-a-query)
  * [Deleting an entire data collection](#deleting-an-entire-data-collection)
  * [Setting up a data mapping on a collection](#setting-up-a-data-mapping-in-a-collection)
  * [Performing a bulk import](#performing-a-bulk-import)

##<a name="how-to-connect-to-kuzzle"></a> How to connect to Kuzzle

To establish communication with Kuzzle using WebSockets, simply connect your application to the Kuzzle's WebSocket port.
By default, the router controller listens to the port 7512 for WebSocket applications.

##<a name="what-are-responses-objects"></a> What are ``response`` objects

A ``response`` is the result of a query you send to Kuzzle. It may be the results of a search query, an acknowledgement of a create action, and so on.  
And when you subscribe to a room, Kuzzle also sends notifications to your application in the form of a ``response`` object.

A ``response`` is a JSON object with the following structure:

```javascript
{
  /*
  String containing an error message if something went wrong
  */
  error: null,  

  /*
  Complex object, depending on your query
  */
  result: {
    requestId: <unique ID>  // Your query unique identifier. See below.
    ...
  }
}
```

Kuzzle will respond to your application by sending a ``requestId`` message on your socket, so you should specify one to get a response. And for some queries, this argument is required, as it wouldn't have any sense for Kuzzle to not be able to send you a response (for instance, when performing a document search).

So to get a response from Kuzzle, simply add an unique ``requestId`` field to your message (for instance by using an [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)), and then listen for a ``requestId`` message on your socket.

##<a name="performing-queries"></a> Performing queries

This section details every query you can send to Kuzzle, and the ``response`` object Kuzzle will send you back, if any.

Each query you make needs to specify:
* what ``action`` you want to perform,
* and the ``data collection`` you want to query

Moreover, you need to emit to Kuzzle a ``controller`` message, where ``controller`` is the Kuzzle component that will execute your query.

This documentation will tell you the corresponding ``controller`` and ``action``. The only thing you need to know is what a ``data collection`` is.  
Simply put, a ``data collection`` is a set of data managed internally by Kuzzle. It acts like a data table for persistent documents, or like a room for pub/sub messages.  


---

###<a name="subscribing-to-documents"></a> Subscribing to documents

Subscription doesn't work the same way in Kuzzle than with a regular publish/subscribe protocol.  
In Kuzzle, you don't exactly subscribe to a room or a topic but, instead, you subscribe to documents.

What it means is that, along with your subscription query, you also give to Kuzzle a set of matching criterias.  
Once you have subscribed to a room, if a pub/sub message is published matching your criterias, or if a matching stored document change (because it is created, updated or deleted), then you'll receive a notification about it.  
Notifications are ``response`` objects.
<commit_msg>markdown formatting<commit_after># Kuzzle WebSocket API Specifications

## Introduction

You can connect your application directly to Kuzzle, using WebSockets.

This will give you a direct access to the Kuzzle's router controller, dispatching your queries to the right components, which in turn will send you back a ``response``


## Index

* [How to connect to Kuzzle](#how-to-connect-to-kuzzle)
* [What are responses objects](#what-are-responses-objects)
* [Performing queries](#performing-queries)
  * [Subscribing to documents](#subscribing-to-documents)
    * [Notifications you can receive](#notifications)
  * [Counting the number of subscriptions on a given room](#counting-the-number-of-subscriptions-on-a-given-room)
  * [Unsubscribing of a room](#unsubscribing-of-a-room)
  * [Sending a publish/subscribe message](#sending-a-publish-subscribe-message)
  * [Creating a new document](#creating-a-new-document)
  * [Retrieving a document](#retrieving-a-document)
  * [Searching for documents](#searching-for-documents)
  * [Updating a document](#updating-a-document)
  * [Counting documents](#counting-documents)
  * [Deleting a document using a document unique ID](#deleting-a-document-using-a-document-unique-id)
  * [Deleting documents using a query](#deleting-documents-using-a-query)
  * [Deleting an entire data collection](#deleting-an-entire-data-collection)
  * [Setting up a data mapping on a collection](#setting-up-a-data-mapping-in-a-collection)
  * [Performing a bulk import](#performing-a-bulk-import)

##<a name="how-to-connect-to-kuzzle"></a> How to connect to Kuzzle

To establish communication with Kuzzle using WebSockets, simply connect your application to the Kuzzle's WebSocket port.
By default, the router controller listens to the port 7512 for WebSocket applications.

##<a name="what-are-responses-objects"></a> What are ``response`` objects

A ``response`` is the result of a query you send to Kuzzle. It may be the results of a search query, an acknowledgement of a create action, and so on.  
And when you subscribe to a room, Kuzzle also sends notifications to your application in the form of a ``response`` object.

A ``response`` is a JSON object with the following structure:

```javascript
{
  /*
  String containing an error message if something went wrong
  */
  error: null,  

  /*
  Complex object, depending on your query
  */
  result: {
    requestId: <unique ID>  // Your query unique identifier. See below.
    ...
  }
}
```

Kuzzle will respond to your application by sending a ``requestId`` message on your socket, so you should specify one to get a response. And for some queries, this argument is required, as it wouldn't have any sense for Kuzzle to not be able to send you a response (for instance, when performing a document search).

So to get a response from Kuzzle, simply add an unique ``requestId`` field to your message (for instance by using an [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)), and then listen for a ``requestId`` message on your socket.

##<a name="performing-queries"></a> Performing queries

This section details every query you can send to Kuzzle, and the ``response`` object Kuzzle will send you back, if any.

Each query you make needs to specify:

* what ``action`` you want to perform,
* and the ``data collection`` you want to query

Moreover, you need to emit to Kuzzle a ``controller`` message, where ``controller`` is the Kuzzle component that will execute your query.

This documentation will tell you the corresponding ``controller`` and ``action``. The only thing you need to know is what a ``data collection`` is.  
Simply put, a ``data collection`` is a set of data managed internally by Kuzzle. It acts like a data table for persistent documents, or like a room for pub/sub messages.  


---

###<a name="subscribing-to-documents"></a> Subscribing to documents

Subscription doesn't work the same way in Kuzzle than with a regular publish/subscribe protocol.  
In Kuzzle, you don't exactly subscribe to a room or a topic but, instead, you subscribe to documents.

What it means is that, along with your subscription query, you also give to Kuzzle a set of matching criterias.  
Once you have subscribed to a room, if a pub/sub message is published matching your criterias, or if a matching stored document change (because it is created, updated or deleted), then you'll receive a notification about it.  
Notifications are ``response`` objects.

{'fraction_non_alphanumeric': 0.09297636384003585, 'fraction_numerical': 0.0008961577237593816, 'mean_word_length': 4.494153846153846, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6920421', 'n_tokens_mistral': 2533, 'n_tokens_neox': 2396, 'n_words': 1123}