Updated a documentation a bit

docs/other/dbquery.rst

@@ -0,0 +1,109 @@
+.. _json-db-query:
+
+JSON Database Query
+===================
+
+JSON Database Query is a special JSON object designed to perform queries against other JSON objects
+(for example, :ref:`User Profiles <user-profile>` or :ref:`Rooms / Parties <game-master-concepts>`), much like SQL
+language, except its very simplified.
+
+    ::
+
+        {
+            "apple": "green",
+            "age": {
+                "@func": ">=",
+                "@value": 18
+            }
+        }
+
+Is equivalent of this SQL query:
+
+    .. code-block:: sql
+
+         SELECT *
+         FROM `table`
+         WHERE `apple`='green' AND `age`>=18;
+
+For example, consider this object:
+
+   ::
+
+       {
+          "username": "player",
+          "level": 50,
+          "progress": {
+              ...
+          }
+       }
+
+If you have such an object in the database, you can find it in the database, using this simple JSON Database Query:
+
+    ::
+
+        {
+            "username": "player"
+        }
+
+
+Query Format
+------------
+
+In general, JSON Database Query has such format:
+
+    ::
+
+        {
+            <field>: value or function,
+            <field>: value or function,
+            ...
+        }
+
+It only works with ``AND`` condition, meaning **ALL** fields of the querying object have to satisfy the query.
+
+* ``value``
+
+    If you specify a value, for example ``"string"`` or ``15``, the query will search for exact value in that field.
+
+* ``function``
+
+    You can pass a function along the way. It will test the field on certain conditions.
+
+Functions
+---------
+
+A function is a JSON object itself, with this exact format:
+
+    ::
+
+        {
+            "@func": "<function name>",
+            "@value": <a value to test the function against>
+        }
+
+Supported functions are: ``>``, ``<``, ``=``, ``>=``, ``<=``, ``!=``, ``between`` and ``in``.
+
+The mathematical ones are obvious, as they do as they're named.
+
+* ``between``
+
+    A special function for searching a field with value between ``a`` and ``b``. It has this exclusive format:
+
+    ::
+
+        {
+            "@func": "between",
+            "@a": 10,
+            "@b": 15,
+        }
+
+* ``in``
+
+    A special function for searching a field with value listed in an array. It has this exclusive format:
+
+    ::
+
+        {
+            "@func": "in",
+            "@values": [1, 2, 4, 8, 16, 32]
+        }

docs/other/profileobject.rst

@@ -487,6 +487,46 @@ Such formula will do nothing if a total number of child objects of the ``members
     This particular function might be used in ``join_party`` method of :ref:`party-session-methods` to test against
     Party Members while joining the party.
 
+Examples
+--------
+
+Increment likes/stats/etc
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: json
+
+    {
+        "likes-x": {
+            "@func": "++",
+            "@value": 1
+        }
+    }
+
+Claim a reward, but only once
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: json
+
+    {
+        "reward-x": {
+            "@func": "!=",
+            "@cond": true,
+            "@then": true
+        }
+    }
+
+Set a value to a filed, only if it didn't exist earlier
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: json
+
+    {
+        "value-x": {
+            "@func": "not_exists",
+            "@then": 55
+        }
+    }
+
 Applications
 ------------
 

docs/services/exec/api.rst

@@ -351,3 +351,62 @@ An object to access to the :doc:`../profile`
     +-------------+-------------------------------------------------------------------------------------------------------------------------------------+
     | ``merge``   | (Optional). If true (default), the JSON objects of existing profile and updated one are mixed, otherwise the old object is replaces |
     +-------------+-------------------------------------------------------------------------------------------------------------------------------------+
+
+- |star| ``profile.query(query, [limit])``
+
+    Search for user profiles with :ref:`json-db-query`.
+
+    .. list-table::
+        :header-rows: 1
+        :widths: 20 80
+
+        * - Argument
+          - Description
+        * - ``profile``
+          - :ref:`json-db-query`
+        * - ``limit``
+          - (Optional) Limit number of resulting profiles, default is 1000.
+
+    A result is a JSON object:
+
+    ::
+
+        {
+            "results": {
+                "1": {
+                    "profile": { ... profile object ... }
+                },
+                "12": {
+                    "profile": { ... profile object ... }
+                },
+                ...
+            },
+            "total_count": <total amount of profiles found>
+        }
+
+admin
+-----
+
+An object for the administrative purposes. Can be accessed only from a server context, and clients have no ways to
+access it.
+
+- |star| ``admin.delete_accounts(accounts, [gamespace_only])``
+
+    .. warning::
+        This actions is destructive and should be proceed with caution. Regular database backups are required before
+        using this.
+
+    Triggers **PERMANENT** deletion of certain accounts from all and every service.
+
+    .. list-table::
+        :header-rows: 1
+        :widths: 20 80
+
+        * - Argument
+          - Description
+        * - ``accounts``
+          - A JSON list of accounts to delete
+        * - ``gamespace_only``
+          - (Optional) Keep the account ID and credentials, so the user can still access data from other gamespaces.
+            Default is true. If true, data will be deleted only from current gamespace.
+            If false, ALL USER DATA FROM ALL GAMESPACES WILL BE PERMANENTLY DELETED.

docs/services/game-master/api.rst

@@ -32,7 +32,7 @@ Returns a list of rooms.
    * - ``game_server_name``
      - Game Server Configuration name, see :ref:`game-master-concepts`
    * - ``settings``
-     - Optional. A JSON object, filtering room's settings.
+     - Optional. A :ref:`json-db-query`, filtering room's settings.
    * - ``show_full``
      - Optional, default is ``true``. To return rooms with maximum players capacity reached, or not.
    * - ``my_region_only``
@@ -167,7 +167,7 @@ you don't see any rooms before joining.
    * - ``game_server_name``
      - Game Server Configuration name, see :ref:`game-master-concepts`
    * - ``settings``
-     - Optional. A JSON object, filtering room's settings.
+     - Optional. A :ref:`json-db-query`, filtering room's settings.
    * - ``auto_create``
      - Optional, default is ``true``. Create a new Room, if there is no suitable one. This will instantiate a new
        Game Server instance. If ``false``, and there is no suitable room, a ``404 Not Found`` will be returned.
@@ -249,7 +249,7 @@ somehow difficult due to the fact that you need authoritative party for it (for
      - A JSON list of accounts ``[1, 20, 444, 888]`` the search fill be performed for. The more accounts the
        more room in the destination room is required.
    * - ``settings``
-     - Optional. A JSON object, filtering room's settings.
+     - Optional. A :ref:`json-db-query`, filtering room's settings.
    * - ``auto_create``
      - Optional, default is ``true``. Create a new Room, if there is no suitable one. This will instantiate a new
        Game Server instance. If ``false``, and there is no suitable room, a ``404 Not Found`` will be returned.
@@ -999,6 +999,8 @@ Additional query artuments:
      - See :ref:`party-properties`
    * - ``room_settings``
      - See :ref:`party-properties`
+   * - ``room_filters``
+     - Optional, A :ref:`json-db-query` in :ref:`party-properties`
    * - ``max_members``
      - See :ref:`party-properties`
    * - ``region``
@@ -1087,10 +1089,10 @@ Additional query arguments:
 
    * - Query Argument
      - Description
-   * - ``party_filter``
-     - A filter to search the parties for. This argument is required.
+   * - ``party_filters``
+     - A JSON Object filter to search the parties for. This argument is required. Simple ``{}`` means no filters.
    * - ``auto_create``
-     - To automatically create a new party if there’s no party that satisfies ``party_filter``. Please note that if ``auto_create`` is ``true``, access scope ``party_create`` is required.
+     - To automatically create a new party if there’s no party that satisfies ``party_filters``. Please note that if ``auto_create`` is ``true``, access scope ``party_create`` is required.
    * - ``member_profile``
      - Member’s profile. See :ref:`party-member-properties`
 
@@ -1106,7 +1108,7 @@ If ``auto_create`` is ``true``, these arguments are expected:
    * - ``create_room_settings``
      - ``room_settings`` in :ref:`party-properties`
    * - ``create_room_filters``
-     - ``room_filters`` in :ref:`party-properties`
+     - ``room_filters`` A :ref:`json-db-query`, in :ref:`party-properties`
    * - ``max_members``
      - See :ref:`party-properties`
    * - ``region``

docs/services/game-master/party.rst

@@ -39,11 +39,11 @@ Each party has a set of properties:
    * - Name
      - Description
    * - ``party_settings``
-     - Abstract JSON object of party-related settings, completely defined by the game. Parties can be found using these settings (see ``party_filter`` argument on some requests below)
-   * - ``room_setting``
-     - Abstract JSON object of the actual room settings that will be applied to the Game Server once the party starts (if the ``room_filter`` below is defined, and an existing room has been found, this field is ignored)
-   * - ``room_filter``
-     - (Optional) If defined the party will search for appropriate room first upon party startup, instead of creating a new one.
+     - Abstract JSON object of party-related settings, completely defined by the game. Parties can be found using these settings (see ``party_filters`` argument on some requests below)
+   * - ``room_settings``
+     - Abstract JSON object of the actual room settings that will be applied to the Game Server once the party starts (if the ``room_filters`` below is defined, and an existing room has been found, this field is ignored)
+   * - ``room_filters``
+     - (Optional) :ref:`json-db-query`, if defined, the party will search for appropriate room first upon party startup, instead of creating a new one.
 
 Additional properties:
 
@@ -348,7 +348,7 @@ A Game Server can detect if it’s being launched in a party context with enviro
 Late connection
 ~~~~~~~~~~~~~~~
 
-In some cases, party members can join the Game Server way after creation of it. For example, if ``room_filter`` is defined inside the party, the existing Game Server will be searched before creating a new one. In that case the party members may connect to existing Game Server that was spawned by another party (or without any party at all).
+In some cases, party members can join the Game Server way after creation of it. For example, if ``room_filters`` is defined inside the party, the existing Game Server will be searched before creating a new one. In that case the party members may connect to existing Game Server that was spawned by another party (or without any party at all).
 
 To deal with this, a Game Server can identify a party member by parsing the ``info`` object of the ``joined`` controller request response. The ``info`` object may contain these fields: ``party_id``, ``party_profile``, ``party_role``, their definitions are described above.
 

docs/services/profile.rst

@@ -1,7 +1,8 @@
 Profile Service
 ===============
 
-A service designed to store player profiles.
+A service designed to store player profiles – special objects to account progress of the Player inside of the game,
+and to sync it remotely from anywhere.
 
 .. seealso::
    :anthill-service-source:`Source Code <profile>`
@@ -14,6 +15,38 @@ User Profile
 User Profile is a JSON :ref:`profile-object` that applied to store Player's data on the server backend.
 It can be altered concurrently, or as a whole JSON object, depending on your requirements.
 
+Transaction Instead of Dump
+---------------------------
+
+A good practice to manage :ref:`user-profile` would be to update it in "transactional style" instead of dumping as is.
+
+For example, say you have this profile object:
+
+    .. code-block:: json
+
+        {
+            "a": 10,
+            "b": 15,
+            "c": 100
+        }
+
+Once you have tracked the field ``c`` has increased it's value by 20 and you would like to store that, instead
+of dumping the whole object, use the :ref:`profile-object` magic:
+
+    .. code-block:: json
+
+        {
+            "c": {
+                "@func": "++",
+                "@value": 20
+            }
+        }
+
+The other fields will be left unchanged, and the field ``c`` will be incremented by 20. The result of the increment will
+be returned, so the server that made the request can update the changed accordingly.
+
+That way, if several parties might alter the profile at the same time, you can ensure that no changes can be lost ever.
+
 Profile Access
 --------------