Database

Source code in src/cocalc_api/hub.py

class Database:

    def __init__(self, parent: "Hub"):
        self._parent = parent

    @api_method("db.userQuery")
    def query(self, query: dict[str, Any]) -> dict[str, Any]:
        """
        Do a user query. The input is of one of the following forms, where the tables are defined at
        https://github.com/sagemathinc/cocalc/tree/master/src/packages/util/db-schema

        - `{"table-name":{"key":"value", ...}}` with no None values sets one record in the database
        - `{"table-name":[{"key":"value", "key2":None...}]}` gets an array of all matching records
          in the database, filling in None's with the actual values.
        - `{"table-name:{"key":"value", "key2":None}}` gets one record, filling in None's with actual values.

        This is used for most configuration, e.g., user names, project descriptions, etc.

        Args:
            query (dict[str, Any]): Object that defines the query, as explained above.

        Examples:
            Get and also change your first name:

            >>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk...")
            >>> hub.db.query({"accounts":{"first_name":None}})
            {'accounts': {'first_name': 'William'}}
            >>> hub.db.query({"accounts":{"first_name":"W"}})
            {}
            >>> hub.db.query({"accounts":{"first_name":None}})
            {'accounts': {'first_name': 'W'}}
        """
        ...  # pragma: no cover

query(query)

Do a user query. The input is of one of the following forms, where the tables are defined at https://github.com/sagemathinc/cocalc/tree/master/src/packages/util/db-schema

• {"table-name":{"key":"value", ...}} with no None values sets one record in the database
• {"table-name":[{"key":"value", "key2":None...}]} gets an array of all matching records in the database, filling in None's with the actual values.
• {"table-name:{"key":"value", "key2":None}} gets one record, filling in None's with actual values.

This is used for most configuration, e.g., user names, project descriptions, etc.

Parameters:

Name	Type	Description	Default
query	dict[str, Any]	Object that defines the query, as explained above.	required

Examples:

Get and also change your first name:

>>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk...")
>>> hub.db.query({"accounts":{"first_name":None}})
{'accounts': {'first_name': 'William'}}
>>> hub.db.query({"accounts":{"first_name":"W"}})
{}
>>> hub.db.query({"accounts":{"first_name":None}})
{'accounts': {'first_name': 'W'}}

Source code in src/cocalc_api/hub.py

@api_method("db.userQuery")
def query(self, query: dict[str, Any]) -> dict[str, Any]:
    """
    Do a user query. The input is of one of the following forms, where the tables are defined at
    https://github.com/sagemathinc/cocalc/tree/master/src/packages/util/db-schema

    - `{"table-name":{"key":"value", ...}}` with no None values sets one record in the database
    - `{"table-name":[{"key":"value", "key2":None...}]}` gets an array of all matching records
      in the database, filling in None's with the actual values.
    - `{"table-name:{"key":"value", "key2":None}}` gets one record, filling in None's with actual values.

    This is used for most configuration, e.g., user names, project descriptions, etc.

    Args:
        query (dict[str, Any]): Object that defines the query, as explained above.

    Examples:
        Get and also change your first name:

        >>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk...")
        >>> hub.db.query({"accounts":{"first_name":None}})
        {'accounts': {'first_name': 'William'}}
        >>> hub.db.query({"accounts":{"first_name":"W"}})
        {}
        >>> hub.db.query({"accounts":{"first_name":None}})
        {'accounts': {'first_name': 'W'}}
    """
    ...  # pragma: no cover