Welcome to ProvSQL's documentation!
===================================

**ProvSQL** is a PostgreSQL extension that adds semiring provenance and
uncertainty management to SQL queries.  It transparently rewrites
queries to track which input tuples contribute to each result, then
evaluates the provenance in any user-chosen semiring -- Boolean
reachability, counting, probability, Shapley values, and more.

A companion Python web UI, **ProvSQL Studio**, provides interactive
provenance inspection on top of any ProvSQL-enabled database.

Both are free, open-source software distributed under the `MIT License
<https://github.com/PierreSenellart/provsql/blob/master/LICENSE>`_.

This documentation is organized into four parts:

* The :ref:`user-guide` explains how to install, configure, and use
  ProvSQL from the SQL level and through ProvSQL Studio.  Start here
  if you are new to ProvSQL.

* The :ref:`case-studies` present extended worked examples of ProvSQL
  applied to realistic scenarios, covering a broader range of features
  than the introductory tutorial.

* The :ref:`dev-guide` describes ProvSQL's internal architecture
  and is aimed at contributors.  It covers the PostgreSQL
  extension concepts ProvSQL relies on, the architecture and
  component map, the query rewriting pipeline, memory management,
  the where-provenance and data-modification subsystems,
  aggregation and semiring evaluation, probability computation,
  coding conventions, testing, debugging, the build system, and
  ProvSQL Studio's architecture.

* The :ref:`api-ref` provides auto-generated reference documentation
  for the SQL and C/C++ APIs (via Doxygen).

.. toctree::
   :hidden:

   ProvSQL’s Documentation <self>

.. _user-guide:

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   user/introduction
   user/getting-provsql
   user/tutorial
   user/provenance-tables
   user/querying
   user/nulls
   user/aggregation
   user/semirings
   user/probabilities
   user/knowledge-compilation
   user/continuous-distributions
   user/conditioning
   user/shapley
   user/where-provenance
   user/data-modification
   user/temporal
   user/export
   user/studio
   user/configuration
   user/tool-registry

.. _case-studies:

.. toctree::
   :maxdepth: 2
   :caption: Case Studies

   user/casestudies
   user/casestudy1
   user/casestudy2
   user/casestudy3
   user/casestudy4
   user/casestudy5
   user/casestudy6
   user/casestudy7
   user/casestudy8

.. _dev-guide:

.. toctree::
   :maxdepth: 2
   :caption: Developer Guide

   dev/introduction
   dev/postgresql-primer
   dev/architecture
   dev/query-rewriting
   dev/memory
   dev/where-provenance
   dev/data-modification
   dev/aggregation
   dev/semiring-evaluation
   dev/probability-evaluation
   dev/kc-server-protocol
   dev/continuous-distributions
   dev/coding-conventions
   dev/testing
   dev/debugging
   dev/build-system
   dev/studio
   dev/playground

.. _api-ref:

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   sql/provsql
   c/provsql

.. toctree::
   :maxdepth: 1
   :caption: References

   user/bibliography
