# HG changeset patch # User Sebastien Jodogne # Date 1469020342 -7200 # Node ID 5737f51ff94e297eb562a914252bb79247ed882f # Parent 922f5c7192c6b24c6174ced4f3fdbd7e66e62faf How does Orthanc stores its database diff -r 922f5c7192c6 -r 5737f51ff94e Sphinx/source/faq.rst --- a/Sphinx/source/faq.rst Wed Jul 20 14:18:47 2016 +0200 +++ b/Sphinx/source/faq.rst Wed Jul 20 15:12:22 2016 +0200 @@ -47,4 +47,5 @@ faq/https.rst faq/same-origin.rst faq/matlab.rst + faq/orthanc-storage.rst faq/why-orthanc.rst diff -r 922f5c7192c6 -r 5737f51ff94e Sphinx/source/faq/orthanc-storage.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/faq/orthanc-storage.rst Wed Jul 20 15:12:22 2016 +0200 @@ -0,0 +1,76 @@ +How does Orthanc stores its database? +===================================== + +Storage folder +-------------- + +**By default** (i.e. if no database plugin such as :ref:`PostgreSQL +` is used), Orthanc stores all the DICOM files it receives +in a folder called ``OrthancStorage`` on the filesystem. Orthanc also +associates each incoming DICOM file with a JSON file that summarizes +all its DICOM tags, which speeds up subsequent processing by avoiding +a costly DICOM parsing. + +More generally, the ``OrthancStorage`` folder contains a set of +so-called **attachments**, that may correspond to either a DICOM file, +a JSON file, or any user-defined file. Internally, each attachment is +automatically associated with an `universally unique identifier (UUID) +`__. +Orthanc can be configured to compress these files on-the-fly in order +to save disk space (cf. the ``StorageCompression`` :ref:`configuration +option `). + +To reduce the number of files in a single directory (which is +something that some operating systems might not like), a 3-level +hierarchy of directories is created to store the attachments: The +first two hexadecimal characters of the UUID give the first-level +folder, and the two next characters give the second-level folder. + + +SQLite index +------------ + +Inside the same ``OrthancStorage`` folder, Orthanc maintains a `SQLite +database `__ called ``index`` +that **indexes** all these attachments. The database records, for each +attachment, its compression method, and its MD5 hashes before and +after compression in order to detect disk corruption (cf. the +``StoreMD5ForAttachments`` :ref:`configuration option +`). + +One attachment must be associated with one :ref:`DICOM resource +` (patient, study, series, or instance). Incoming DICOM +files and associated JSON summary are associated with one +instance-level resource, but user-defined attachments can be +associated with any kind of resource. + +Given one DICOM resource, all of its child attachments are identified +by a number between 0 and 65535. Identifiers <= 1023 are reserved for +the Orthanc core, whereas identifiers >= 1024 can be user-defined for +external applications. + + +Direct access +------------- + +Directly accessing the content of the ``OrthancStorage`` folder and +the content of the SQLite database is strongly discouraged for several +reasons: + +* This internal organization is only true when no database plugin is + used (e.g. the :ref:`PostgreSQL plugin ` can be + configured to store the attachments inside a database). +* Orthanc can be configured to compress the attachments before writing + them on the disk (cf. the ``StorageCompression`` option). +* By directly reading the content of ``OrthancStorage``, you bypass + all the locking mechanisms used by Orthanc, which might result in + data corruption. + +As a consequence, it is **HIGHLY recommended NOT to directly access** +the ``OrthancStorage`` folder and the SQLite database. Use the +:ref:`REST API ` instead, which contains primitives to access +the attachments (cf. the ``.../attachments/...`` URIs). + +The only exception to this rule is for **read-only access when Orthanc +is stopped**, e.g. as a part of a :ref:`backup ` or +:ref:`upgrade/replication ` process. diff -r 922f5c7192c6 -r 5737f51ff94e Sphinx/source/users/rest.rst --- a/Sphinx/source/users/rest.rst Wed Jul 20 14:18:47 2016 +0200 +++ b/Sphinx/source/users/rest.rst Wed Jul 20 15:12:22 2016 +0200 @@ -574,5 +574,12 @@ The examples above have shown you the basic principles for driving an instance of Orthanc through its REST API. All the possibilities of the -API have not been described. A :ref:`FAQ entry ` lists -where you can find more advanced samples of the REST API of Orthanc. +API have not been described: + +* A :ref:`FAQ entry ` lists where you can find more + advanced samples of the REST API of Orthanc. +* The full documentation of the REST API is maintained as an online + spreadsheet accessible from the `documentation part of the official + Web site + `__ + (click on the *Reference of the REST API* button).