#################### Defining SQL Queries #################### Query Names & Comments ====================== Name definitions are how ``anosql`` determines how to name the SQL code blocks which are loaded. A query name definition is a normal SQL comment starting with "-- name:" and is followed by the name of the query. You can use ``-`` or ``_`` in your query names, but the methods in python will always be valid python names using underscores. .. code-block:: sql -- name: get-all-blogs select * from blogs; The above example when loaded by ``anosql.from_path`` will return an object with a ``.get_all_blogs(conn)`` method. Your SQL comments will be added to your methods as python documentation, and accessible by calling ``help()`` on them. .. code-block:: sql -- name: get-all-blogs -- Fetch all fields for every blog in the database. select * from blogs; .. code-block:: python queries = anosql.from_path("blogs.sql", "sqlite3") help(anosql.get_all_blogs) output .. code-block:: text Help on function get_user_blogs in module anosql.anosql: get_all_blogs(conn, *args, **kwargs) Fetch all fields for every blog in the database. .. _query-operations: Query Operations ================ Adding query operator symbols to the end of query names will inform ``anosql`` of how to execute and return results. In the above section the ``get-all-blogs`` name has no special operator characters trailing it. This lack of operator is actually the most basic operator which performs SQL ``select`` statements and returns a list of rows. When writing an application you will often need to perform other operations besides selects, like inserts, deletes, and bulk opearations. The operators detailed in this section let you declare in your SQL, how your code should be executed by the database driver. Insert/Update/Delete with ``!`` ------------------------------- The ``!`` operator will execute SQL without returning any results. It is meant for use with ``insert``, ``update``, and ``delete`` statements for which returned data is not required. .. code-block:: sql -- name: publish-blog! insert into blogs(userid, title, content) values (:userid, :title, :content); -- name: remove-blog! -- Remove a blog from the database delete from blogs where blogid = :blogid; The methods generated are: - ``publish_blog(conn, *args, **kwargs)`` - ``remove_blog(conn, *args, **kwargs)`` Each of them can be run to alter the database, but both will return ``None``. Insert Returning with ``