skytable/actiondoc.yml

#
#  Created on Thu Aug 27 2020
#
#  This file is a part of Skytable
#  Skytable (formerly known as TerrabaseDB or Skybase) is a free and open-source
#  NoSQL database written by Sayan Nandan ("the Author") with the
#  vision to provide flexibility in data modelling without compromising
#  on performance, queryability or scalability.
#
#  Copyright (c) 2020, Sayan Nandan <ohsayan@outlook.com>
#
#  This program is free software: you can redistribute it and/or modify
#  it under the terms of the GNU Affero General Public License as published by
#  the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
#  GNU Affero General Public License for more details.
#
#  You should have received a copy of the GNU Affero General Public License
#  along with this program. If not, see <https://www.gnu.org/licenses/>.
#
#
#
#  This file is used by Skytable's documentation website for automatically
#  generating documentation for the actions. It will also be used by the Skytable
#  server in the future

# the docbuilder expects:
# 'name': str, 'complexity': str, 'accept': [str]
# 'return': [str], 'syntax': [str], 'desc': str

global:
  - name: HEYA
    complexity: O(1)
    accept: [AnyArray]
    syntax: [HEYA, HEYA <message>]
    desc: |
            Either returns a "HEY!" or returns the provided argument as an `str`
    return: [String]
  - name: DBSIZE
    complexity: O(1)
    accept: [AnyArray]
    syntax: [DBSIZE, DBSIZE <entity>]
    desc: Check the number of entries stored in the current table or in the provided entity
    return: [Integer]
  - name: MKSNAP
    complexity: O(n)
    accept: [AnyArray]
    syntax: [MKSNAP, MKSNAP <SNAPNAME>]
    desc: |
      This action can be used to create a snapshot. Do note that this action **requires
      snapshotting to be enabled on the server side**, before it can create snapshots.
      If you want to create snapshots **without** snapshots being enabled on the server-side,
      pass a second argument `<SNAPNAME>` to specify a snapshot name and a snapshot will
      be create in a folder called `rsnap` under your data directory. For more
      information on snapshots, read [this document](/snapshots)      
    return: [Rcode 0, err-snapshot-disabled, err-snapshot-busy]
  - name: FLUSHDB
    complexity: O(n)
    accept: [AnyArray]
    syntax: [FLUSHDB, FLUSHDB <entity>]
    desc: Removes all entries stored in the current table or in the provided entity
    return: [Rcode 0, Rcode 5]
  - name: WHEREAMI
    complexity: O(1)
    accept: [AnyArray]
    syntax: [WHEREAMI]
    desc: |
      Returns an array with either the name of the current keyspace as the first element or if a default table
      is set, then it returns the keyspace name as the first element and the table name as the second element      
    return: [Non-null array]
  - name: AUTH
    desc: Change global authn/authz settings
    subactions:
      - name: LOGIN
        complexity: O(1)
        accept: [AnyArray]
        syntax: [AUTH LOGIN <username> <token>]
        desc: Attempts to log in using the provided credentials
        return: [Rcode 0, Rcode 10]
      - name: CLAIM
        complexity: O(1)
        accept: [AnyArray]
        syntax: [AUTH CLAIM <origin key>]
        desc: Attempts to claim the root account using the origin key
        return: [String, Rcode 10]
      - name: LOGOUT
        complexity: O(1)
        accept: [AnyArray]
        syntax: [AUTH LOGOUT]
        desc: Attempts to log out the currently logged in user
        return: [Rcode 0, Rcode 10]
      - name: ADDUSER
        complexity: O(1)
        accept: [AnyArray]
        syntax: [AUTH ADDUSER <username>]
        desc: Attempts to create a new user with the provided username, returning the token
        return: [String, Rcode 11]
      - name: DELUSER
        complexity: O(1)
        accept: [AnyArray]
        syntax: [AUTH DELUSER <username>]
        desc: Attempts to delete the user with the provided username
        return: [Rcode 0, Rcode 10, Rcode 11]
      - name: RESTORE
        complexity: O(1)
        accept: [AnyArray]
        syntax: [AUTH RESTORE <username>, AUTH RESTORE <origin-key> <username>]
        desc: |
          Attempts to restore the password for the provided user. This will regenerate the token
          and return the newly issued token. However, if you aren't a root account, that is, you
          lost your root password, then you'll need to run `AUTH RESTORE <origin-key> root`.          
        return: [String, Rcode 10, Rcode 11]
      - name: LISTUSER
        complexity: O(1)
        accept: [AnyArray]
        syntax: [AUTH LISTUSER]
        desc: |
                    Attempts to return a list of users for the current database instance
        return: [Non-null array]
      - name: WHOAMI
        complexity: O(1)
        accept: [AnyArray]
        syntax: [AUTH WHOAMI]
        desc: |
          Returns a string with the AuthID of the currently logged in user or errors if the user
          is not logged in          
        return: [String]
  - name: SYS
    desc: |
            Get system information and metrics
    subactions:
      - name: INFO
        complexity: O(1)
        accept: [AnyArray]
        syntax: [sys info <property>]
        return: [String, Float]
        desc: |
          Returns static properties of the system, i.e properties that do not change during runtime.
          The following properties are available:
            - `version`: Returns the server version (String)
            - `protocol`: Returns the protocol version string (String)
            - `protover`: Returns the protocol version (float)          
      - name: METRIC
        complexity: O(1)
        accept: [AnyArray]
        syntax: [sys metric <metric>]
        return: [String, Float]
        desc: |
          Returns dynamic properties of the system, i.e metrics are properties that can change during
          runtime. The following metrics are available:
            - `health`: Returns "good" or "critical" depending on the system state (String)
            - `storage`: Returns bytes used for on-disk storage (uint64)          

keyvalue:
  generic:
    - name: DEL
      complexity: O(n)
      accept: [AnyArray]
      syntax: [DEL <key1> <key2> ...]
      desc: |
        Delete 'n' keys from the current table. This will return the number of keys that were deleted
        as an unsigned integer        
      return: [Integer, Rcode 5]
    - name: EXISTS
      complexity: O(n)
      accept: [AnyArray]
      syntax: [EXISTS <key1> <key2> ...]
      desc: |
        Check if 'n' keys exist in the current table. This will return the number of keys that exist
        as an unsigned integer.        
      return: [Integer]
    - name: LSKEYS
      complexity: O(n)
      accept: [AnyArray]
      syntax: [LSKEYS <limit>, LSKEYS <entity>, LSKEYS <entity> <limit>]
      desc: |
        Returns a flat string array of keys present in the current table or in the provided entity.
        If no `<limit>` is given, then a maximum of 10 keys are returned. If a limit is specified,
        then a maximum of `<limit>` keys are returned. The order of keys is meaningless.        
      return: [Typed Array]
  string:
    - name: GET
      complexity: O(1)
      accept: [AnyArray]
      syntax: [GET <key>]
      desc: Get the value of a key from the current table, if it exists
      return: [Rcode 1, String, Binstr]
    - name: MGET
      complexity: O(n)
      accept: [AnyArray]
      syntax: [MGET <key1> <key2> ...]
      desc: Get the value of 'n' keys from the current table, if they exist
      return: [Typed Array]
    - name: SET
      complexity: O(1)
      accept: [AnyArray]
      syntax: [SET <key> <value>]
      desc: Set the value of a key in the current table, if it doesn't already exist
      return: [Rcode 0, Rcode 2, Rcode 5]
    - name: MSET
      complexity: O(n)
      accept: [AnyArray]
      syntax: [MSET <key1> <value1> <key2> <value2> ...]
      desc: |
        Set the value of 'n' keys in the current table, if they don't already exist. This will
        return the number of keys that were set as an unsigned integer.        
      return: [Integer, Rcode 5]
    - name: UPDATE
      complexity: O(1)
      accept: [AnyArray]
      syntax: [UPDATE <key> <value>]
      desc: Update the value of an existing key in the current table
      return: [Rcode 0, Rcode 1, Rcode 5]
    - name: MUPDATE
      complexity: O(n)
      accept: [AnyArray]
      syntax: [MUPDATE <key1> <value1> <key2> <value2> ...]
      desc: |
        Update the value of 'n' keys in the current table, if they already exist. This will return
        the number of keys that were updated as an unsigned integer.        
      return: [Integer, Rcode 5]
    - name: SSET
      complexity: O(n)
      accept: [AnyArray]
      syntax: [SSET <key1> <value1> <key2> <value2> ...]
      desc: Set all keys to the given values only if all of them don't exist in the current table
      return: [Rcode 0, Rcode 2, Rcode 5]
    - name: SDEL
      complexity: O(n)
      accept: [AnyArray]
      syntax: [SDEL <key1> <key2> ...]
      desc: |
        Delete all keys if all of the keys exist in the current table. Do note that if a single key doesn't
        exist, then a `Nil` code is returned.        
      return: [Rcode 0, Rcode 1, Rcode 5]
    - name: SUPDATE
      complexity: O(n)
      accept: [AnyArray]
      syntax: [SUPDATE <key1> <value1> <key2> <value2> ...]
      desc: |
        Update all keys if all of the keys exist in the current table. Do note that if a single key doesn't
        exist, then a `Nil` code is returned.        
      return: [Rcode 0, Rcode 1, Rcode 5]
    - name: USET
      complexity: O(n)
      accept: [AnyArray]
      syntax: [USET <key1> <value1> <key2> <value2> ...]
      desc: SET all keys if they don't exist, or UPDATE them if they do exist. This operation performs `USET`s in the current table
      return: [Integer, Rcode 5]
    - name: KEYLEN
      complexity: O(1)
      accept: [AnyArray]
      syntax: [KEYLEN <key>]
      desc: Returns the length of the UTF-8 string, if it exists in the current table
      return: [Integer, Rcode 1]
    - name: POP
      complexity: O(1)
      accept: [AnyArray]
      syntax: [POP <key>]
      desc: |
        Deletes and return the value of the provided key from the current table.
        If the database is poisoned, this will return a server error.        
      return: [String, Binstr, Rcode 5]
    - name: MPOP
      complexity: O(n)
      accept: [AnyArray]
      syntax: [MPOP <key1> <key2> ...]
      desc: |
        Deletes and returns the values of the provided 'n' keys from the current table.
        If the database is poisoned, this will return a server error        
      return: [Typed Array, Rcode 5]
  lists:
    - name: LGET
      desc: |
        `LGET` can be used to access the items in a list. Through the sub-actions provided by `lget`,
         you can access multiple or individual elements in lists.        
      subactions:
        - name: LGET
          complexity: O(n)
          accept: [AnyArray]
          syntax: [LGET <list>]
          desc: |
            Returns all the values contained in a the provided list, if it exists in the current
            table.            
          return: [Typed Array, Rcode 1]
        - name: limit
          complexity: O(n)
          accept: [AnyArray]
          syntax: [LGET <list> limit <limit>]
          desc: Returns a maximum of `limit` values from the provided list, if it exists in the current table
          return: [Typed Array, Rcode 1]
        - name: len
          complexity: O(1)
          accept: [AnyArray]
          syntax: [LGET <list> len]
          desc: Returns the length of the list
          return: [Integer, Rcode 1]
        - name: valueat
          complexity: O(1)
          accept: [AnyArray]
          syntax: [LGET <list> valueat <index>]
          desc: Returns the element present at the provided `index`, if it exists in the given list.
          return: [String, binstr, Rcode 1, bad-list-index]
        - name: first
          complexity: O(1)
          accept: [AnyArray]
          syntax: [LGET <list> first]
          desc: Returns the first element present in the list, if it exists.
          return: [String, binstr, Rcode 1, list-is-empty]
        - name: last
          complexity: O(1)
          accept: [AnyArray]
          syntax: [LGET <list> last]
          desc: Returns the last element present in the list, if it exists.
          return: [String, binstr, Rcode 1, list-is-empty]
        - name: range
          complexity: O(n)
          accept: [AnyArray]
          syntax: [LGET <list> range <start>, LGET <list> range <start> <stop>]
          desc: |
            Returns items in the given range. If no value for `stop` is provided, all the elements from that
            index are returned. If a value for `stop` is provided, then a subarray is returned            
          return: [Typed Array, Rcode 1, bad-list-index]
    - name: LMOD
      desc: |
                `LMOD` can be used to mutate the elements in a list
      subactions:
        - name: push
          complexity: O(1)
          accept: [AnyArray]
          syntax: [LMOD <list> push <v1> <v2> ...]
          desc: Appends the elements to the end of the provided list, if it exists.
          return: [Rcode 0, Rcode 1, Rcode 5]
        - name: insert
          complexity: O(1)
          accept: [AnyArray]
          syntax: [LMOD <list> insert <index> <value>]
          desc: |
            Inserts the element to the provided index, if it is valid while shifting elements
            to the right if required            
          return: [Rcode 0, Rcode 1, Rcode 5, bad-list-index]
        - name: pop
          complexity: O(1)
          accept: [AnyArray]
          syntax: [LMOD <list> pop, LMOD <list> pop <index>]
          desc: |
            Removes the element from the end of the list if no index is provided or from the provided
            index while shifting elements to the right if required.            
          return: [String, Binstr, Rcode 1, Rcode 5, bad-list-index]
        - name: remove
          complexity: O(1)
          accept: [AnyArray]
          syntax: [LMOD <list> remove <index>]
          desc: |
            Removes the element at the provided index from the list, shifting elements to the right
            if required.            
          return: [Rcode 0, Rcode 1, Rcode 5, bad-list-index]
        - name: clear
          complexity: O(n)
          accept: [AnyArray]
          syntax: [LMOD <list> clear]
          desc: |
                        Removes all the elements present in the list
          return: [Rcode 0, Rcode 1, Rcode 5]
    - name: LSET
      desc: |
                `LSET` can be used to create empty lists or lists with the provided values.
      subactions:
        - name: LSET
          complexity: O(n)
          accept: [AnyArray]
          syntax: [LSET <list>, LSET <list> <value1> <value2> ...]
          desc: |
            Creates a list with the provided values, or simply creates an empty list if it doesn't
            already exist in the table.            
          return: [Rcode 0, Rcode 2, Rcode 5]