globals.go 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267
  1. /*
  2. * EliasDB
  3. *
  4. * Copyright 2016 Matthias Ladkau. All rights reserved.
  5. *
  6. * This Source Code Form is subject to the terms of the Mozilla Public
  7. * License, v. 2.0. If a copy of the MPL was not distributed with this
  8. * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  9. */
  10. /*
  11. Package graph contains the main API to the graph datastore.
  12. Manager API
  13. The main API is provided by a Manager object which can be created with the
  14. NewGraphManager() constructor function. The manager CRUD functionality for
  15. nodes and edges through store, fetch and remove functions. It also provides
  16. the basic traversal functionality which allos the traversal from one node to
  17. other nodes.
  18. Node iterator
  19. All available node keys in a partition of a given kind can be iterated by using
  20. a NodeKeyIterator. The manager can produce these with the NodeKeyIterator()
  21. function.
  22. Fulltext search
  23. All nodes and edges in the datastore are indexed. The index can be queried
  24. using a IndexQuery object. The manager can produce these with the NodeIndexQuery()
  25. or EdgeIndexQuery function.
  26. Transactions
  27. A transaction is used to build up multiple store and delete tasks for the
  28. graph database. Nothing is written to the database before calling commit().
  29. A transaction commit does an automatic rollback if an error occurs
  30. (except fatal disk write errors which might cause a panic).
  31. A trans object can be created with the NewGraphTrans() function.
  32. Rules
  33. (Use with caution)
  34. Graph rules provide automatic operations which help to keep the graph consistent.
  35. Rules trigger on global graph events. The rules SystemRuleDeleteNodeEdges and
  36. SystemRuleUpdateNodeStats are automatically loaded when a new Manager is created.
  37. See the code for further details.
  38. Graph databases
  39. A graph manager handles the graph storage and provides the API for
  40. the graph database. The storage is divided into several databases:
  41. Main database
  42. MainDB stores various meta information such as known node/edge kinds, attributes
  43. or version information.
  44. Names database
  45. Names can be encoded (into a number) or decoded (into a string)
  46. 32 bit values for any given node attribute names
  47. 16 bit values for any given edge role names
  48. 16 bit values for any given edge kind names
  49. Nodes database
  50. Each node kind database stores:
  51. PrefixNSAttrs + node key -> [ ATTRS ]
  52. (a list of attributes of a certain node)
  53. PrefixNSAttr + node key + attr num -> value
  54. (attribute value of a certain node)
  55. PrefixNSSpecs + node key -> map[spec]<empty string>
  56. (a lookup for available specs for a certain node)
  57. PrefixNSEdge + node key + spec -> map[edge key]edgeinfo{other node key, other node kind}]
  58. (connection from one node to another via a spec)
  59. Edges database
  60. Each edge kind database stores:
  61. PrefixNSAttrs + edge key -> [ ATTRS ]
  62. (a list of attributes of a certain edge)
  63. PrefixNSAttr + edge key + attr num -> value
  64. (attribute value of a certain edge)
  65. Index database
  66. The text index managed by util/indexmanager.go. IndexQuery provides access to
  67. the full text search index.
  68. */
  69. package graph
  70. /*
  71. VERSION of the GraphManager
  72. */
  73. const VERSION = 1
  74. /*
  75. MainDBEntryPrefix is the prefix for entries stored in the main database
  76. */
  77. const MainDBEntryPrefix = "\x02"
  78. // MainDB entries
  79. // ==============
  80. /*
  81. MainDBVersion is the MainDB entry key for version information
  82. */
  83. const MainDBVersion = MainDBEntryPrefix + "ver"
  84. /*
  85. MainDBNodeKinds is the MainDB entry key for node kind information
  86. */
  87. const MainDBNodeKinds = MainDBEntryPrefix + "nodekind"
  88. /*
  89. MainDBEdgeKinds is the MainDB entry key for edge kind information
  90. */
  91. const MainDBEdgeKinds = MainDBEntryPrefix + "edgekind"
  92. /*
  93. MainDBParts is the MainDB entry key for partition information
  94. */
  95. const MainDBParts = MainDBEntryPrefix + "part"
  96. /*
  97. MainDBNodeAttrs is the MainDB entry key for a list of node attributes
  98. */
  99. const MainDBNodeAttrs = MainDBEntryPrefix + "natt"
  100. /*
  101. MainDBNodeEdges is the MainDB entry key for a list of node relationships
  102. */
  103. const MainDBNodeEdges = MainDBEntryPrefix + "nrel"
  104. /*
  105. MainDBNodeCount is the MainDB entry key for a node count
  106. */
  107. const MainDBNodeCount = MainDBEntryPrefix + "ncnt"
  108. /*
  109. MainDBEdgeAttrs is the MainDB entry key for a list of edge attributes
  110. */
  111. const MainDBEdgeAttrs = MainDBEntryPrefix + "eatt"
  112. /*
  113. MainDBEdgeCount is the MainDB entry key for an edge count
  114. */
  115. const MainDBEdgeCount = MainDBEntryPrefix + "ecnt"
  116. // Root IDs for StorageManagers
  117. // ============================
  118. /*
  119. RootIDNodeHTree is the root ID for the HTree holding primary information
  120. */
  121. const RootIDNodeHTree = 2
  122. /*
  123. RootIDNodeHTreeSecond is the root ID for the HTree holding secondary information
  124. */
  125. const RootIDNodeHTreeSecond = 3
  126. // Suffixes for StorageManagers
  127. // ============================
  128. /*
  129. StorageSuffixNodes is the suffix for a node storage
  130. */
  131. const StorageSuffixNodes = ".nodes"
  132. /*
  133. StorageSuffixNodesIndex is the suffix for a node index
  134. */
  135. const StorageSuffixNodesIndex = ".nodeidx"
  136. /*
  137. StorageSuffixEdges is the suffix for an edge storage
  138. */
  139. const StorageSuffixEdges = ".edges"
  140. /*
  141. StorageSuffixEdgesIndex is the suffix for an edge index
  142. */
  143. const StorageSuffixEdgesIndex = ".edgeidx"
  144. // PREFIXES for Node storage
  145. // =========================
  146. // Prefixes are only one byte. They should be followed by the node key so
  147. // similar entries are stored near each other physically.
  148. //
  149. /*
  150. PrefixNSAttrs is the prefix for storing attributes of a node
  151. */
  152. const PrefixNSAttrs = "\x01"
  153. /*
  154. PrefixNSAttr is the prefix for storing the value of a node attribute
  155. */
  156. const PrefixNSAttr = "\x02"
  157. /*
  158. PrefixNSSpecs is the prefix for storing specs of edges related to a node
  159. */
  160. const PrefixNSSpecs = "\x03"
  161. /*
  162. PrefixNSEdge is the prefix for storing a link from a node (and a spec) to an edge
  163. */
  164. const PrefixNSEdge = "\x04"
  165. // Graph events
  166. //=============
  167. /*
  168. EventNodeCreated is thrown when a node gets created.
  169. Parameters: partition of created node, created node
  170. */
  171. const EventNodeCreated = 0x01
  172. /*
  173. EventNodeUpdated is thrown when a node gets updated.
  174. Parameters: partition of updated node, updated node, old node
  175. */
  176. const EventNodeUpdated = 0x02
  177. /*
  178. EventNodeDeleted is thrown when a node gets deleted.
  179. Parameters: partition of deleted node, deleted node
  180. */
  181. const EventNodeDeleted = 0x03
  182. /*
  183. EventEdgeCreated is thrown when an edge gets created.
  184. Parameters: partition of created edge, created edge
  185. */
  186. const EventEdgeCreated = 0x04
  187. /*
  188. EventEdgeUpdated is thrown when an edge gets updated.
  189. Parameters: partition of updated edge, updated edge, old edge
  190. */
  191. const EventEdgeUpdated = 0x05
  192. /*
  193. EventEdgeDeleted is thrown when an edge gets deleted.
  194. Parameters: partition of deleted edge, deleted edge
  195. */
  196. const EventEdgeDeleted = 0x06