Mercurial > hg > orthanc-book

comparison Sphinx/source/faq/orthanc-storage.rst @ 35:5737f51ff94e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
How does Orthanc stores its database
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 20 Jul 2016 15:12:22 +0200
parents
children 6474af38dcbd
comparison
equal deleted inserted replaced
34:922f5c7192c6 35:5737f51ff94e
1 How does Orthanc stores its database?
2 =====================================
3
4 Storage folder
5 --------------
6
7 **By default** (i.e. if no database plugin such as :ref:`PostgreSQL
8 <postgresql>` is used), Orthanc stores all the DICOM files it receives
9 in a folder called ``OrthancStorage`` on the filesystem. Orthanc also
10 associates each incoming DICOM file with a JSON file that summarizes
11 all its DICOM tags, which speeds up subsequent processing by avoiding
12 a costly DICOM parsing.
13
14 More generally, the ``OrthancStorage`` folder contains a set of
15 so-called **attachments**, that may correspond to either a DICOM file,
16 a JSON file, or any user-defined file. Internally, each attachment is
17 automatically associated with an `universally unique identifier (UUID)
18 <https://en.wikipedia.org/wiki/Universally_unique_identifier>`__.
19 Orthanc can be configured to compress these files on-the-fly in order
20 to save disk space (cf. the ``StorageCompression`` :ref:`configuration
21 option <configuration>`).
22
23 To reduce the number of files in a single directory (which is
24 something that some operating systems might not like), a 3-level
25 hierarchy of directories is created to store the attachments: The
26 first two hexadecimal characters of the UUID give the first-level
27 folder, and the two next characters give the second-level folder.
28
29
30 SQLite index
31 ------------
32
33 Inside the same ``OrthancStorage`` folder, Orthanc maintains a `SQLite
34 database <https://en.wikipedia.org/wiki/SQLite>`__ called ``index``
35 that **indexes** all these attachments. The database records, for each
36 attachment, its compression method, and its MD5 hashes before and
37 after compression in order to detect disk corruption (cf. the
38 ``StoreMD5ForAttachments`` :ref:`configuration option
39 <configuration>`).
40
41 One attachment must be associated with one :ref:`DICOM resource
42 <model-world>` (patient, study, series, or instance). Incoming DICOM
43 files and associated JSON summary are associated with one
44 instance-level resource, but user-defined attachments can be
45 associated with any kind of resource.
46
47 Given one DICOM resource, all of its child attachments are identified
48 by a number between 0 and 65535. Identifiers <= 1023 are reserved for
49 the Orthanc core, whereas identifiers >= 1024 can be user-defined for
50 external applications.
51
52
53 Direct access
54 -------------
55
56 Directly accessing the content of the ``OrthancStorage`` folder and
57 the content of the SQLite database is strongly discouraged for several
58 reasons:
59
60 * This internal organization is only true when no database plugin is
61 used (e.g. the :ref:`PostgreSQL plugin <postgresql>` can be
62 configured to store the attachments inside a database).
63 * Orthanc can be configured to compress the attachments before writing
64 them on the disk (cf. the ``StorageCompression`` option).
65 * By directly reading the content of ``OrthancStorage``, you bypass
66 all the locking mechanisms used by Orthanc, which might result in
67 data corruption.
68
69 As a consequence, it is **HIGHLY recommended NOT to directly access**
70 the ``OrthancStorage`` folder and the SQLite database. Use the
71 :ref:`REST API <rest>` instead, which contains primitives to access
72 the attachments (cf. the ``.../attachments/...`` URIs).
73
74 The only exception to this rule is for **read-only access when Orthanc
75 is stopped**, e.g. as a part of a :ref:`backup <backup>` or
76 :ref:`upgrade/replication <replication>` process.