1dets(3)                    Erlang Module Definition                    dets(3)
2
3
4

NAME

6       dets - A disk-based term storage.
7

DESCRIPTION

9       This  module provides a term storage on file. The stored terms, in this
10       module called objects, are tuples such that one element is  defined  to
11       be the key. A Dets table is a collection of objects with the key at the
12       same position stored on a file.
13
14       This module is used by the Mnesia application, and is provided "as  is"
15       for  users  who  are interested in efficient storage of Erlang terms on
16       disk only. Many applications only need to store some terms in  a  file.
17       Mnesia  adds  transactions, queries, and distribution. The size of Dets
18       files cannot exceed 2 GB. If larger tables are needed, table fragmenta‐
19       tion in Mnesia can be used.
20
21       Three types of Dets tables exist:
22
23         * set.  A table of this type has at most one object with a given key.
24           If an object with a key already present in the table  is  inserted,
25           the existing object is overwritten by the new object.
26
27         * bag. A table of this type has zero or more different objects with a
28           given key.
29
30         * duplicate_bag. A table of this  type  has  zero  or  more  possibly
31           matching objects with a given key.
32
33       Dets tables must be opened before they can be updated or read, and when
34       finished they must be properly closed.  If  a  table  is  not  properly
35       closed,  Dets automatically repairs the table. This can take a substan‐
36       tial time if the table is large.  A  Dets  table  is  closed  when  the
37       process  which  opened  the  table terminates. If many Erlang processes
38       (users) open the same Dets table, they share the table.  The  table  is
39       properly closed when all users have either terminated or closed the ta‐
40       ble. Dets tables are not properly closed if the Erlang  runtime  system
41       terminates abnormally.
42
43   Note:
44       A  ^C  command abnormally terminates an Erlang runtime system in a Unix
45       environment with a break-handler.
46
47
48       As all operations performed by Dets are disk operations, it  is  impor‐
49       tant  to  realize  that a single look-up operation involves a series of
50       disk seek and read operations. The Dets functions  are  therefore  much
51       slower than the corresponding ets(3) functions, although Dets exports a
52       similar interface.
53
54       Dets organizes data as a linear hash  list  and  the  hash  list  grows
55       gracefully as more data is inserted into the table. Space management on
56       the file is performed by what is called a buddy system. The current im‐
57       plementation  keeps  the entire buddy system in RAM, which implies that
58       if the table gets heavily fragmented, quite some memory can be used up.
59       The  only  way  to  defragment  a table is to close it and then open it
60       again with option repair set to force.
61
62       Notice that type ordered_set in Ets is not yet provided by  Dets,  nei‐
63       ther  is  the  limited  support for concurrent updates that makes a se‐
64       quence of first and next calls safe to use on fixed  ETS  tables.  Both
65       these  features  may  be  provided  by  Dets in a future release of Er‐
66       lang/OTP. Until then, the Mnesia application (or some  user-implemented
67       method  for  locking)  must be used to implement safe concurrency. Cur‐
68       rently, no Erlang/OTP library has support for ordered  disk-based  term
69       storage.
70
71       All  Dets  functions return {error, Reason} if an error occurs (first/1
72       and next/2 are exceptions, they exit the process with the error tuple).
73       If badly formed arguments are specified, all functions exit the process
74       with a badarg message.
75

DATA TYPES

77       access() = read | read_write
78
79       auto_save() = infinity | integer() >= 0
80
81       bindings_cont()
82
83              Opaque continuation used by match/1 and match/3.
84
85       cont()
86
87              Opaque continuation used by bchunk/2.
88
89       keypos() = integer() >= 1
90
91       match_spec() = ets:match_spec()
92
93              Match specifications, see section  Match Specification in Erlang
94              in ERTS User's Guide and the ms_transform(3) module.
95
96       no_slots() = default | integer() >= 0
97
98       object() = tuple()
99
100       object_cont()
101
102              Opaque continuation used by match_object/1 and match_object/3.
103
104       pattern() = atom() | tuple()
105
106              For a description of patterns, see ets:match/2.
107
108       select_cont()
109
110              Opaque continuation used by select/1 and select/3.
111
112       tab_name() = term()
113
114       type() = bag | duplicate_bag | set
115

EXPORTS

117       all() -> [tab_name()]
118
119              Returns a list of the names of all open tables on this node.
120
121       bchunk(Name, Continuation) ->
122                 {Continuation2, Data} |
123                 '$end_of_table' |
124                 {error, Reason}
125
126              Types:
127
128                 Name = tab_name()
129                 Continuation = start | cont()
130                 Continuation2 = cont()
131                 Data = binary() | tuple()
132                 Reason = term()
133
134              Returns a list of objects stored in a table. The exact represen‐
135              tation of the returned objects is not public. The lists of  data
136              can  be used for initializing a table by specifying value bchunk
137              to option format of function init_table/3 The Mnesia application
138              uses this function for copying open tables.
139
140              Unless  the  table  is protected using safe_fixtable/2, calls to
141              bchunk/2 do possibly not work as expected if concurrent  updates
142              are made to the table.
143
144              The  first time bchunk/2 is called, an initial continuation, the
145              atom start, must be provided.
146
147              bchunk/2 returns a tuple {Continuation2, Data}, where Data is  a
148              list  of  objects. Continuation2 is another continuation that is
149              to be passed on to a subsequent call to bchunk/2. With a  series
150              of calls to bchunk/2, all table objects can be extracted.
151
152              bchunk/2  returns '$end_of_table' when all objects are returned,
153              or {error, Reason} if an error occurs.
154
155       close(Name) -> ok | {error, Reason}
156
157              Types:
158
159                 Name = tab_name()
160                 Reason = term()
161
162              Closes a table. Only processes that have opened a table are  al‐
163              lowed to close it.
164
165              All  open tables must be closed before the system is stopped. If
166              an attempt is made to open a table that is not properly  closed,
167              Dets automatically tries to repair it.
168
169       delete(Name, Key) -> ok | {error, Reason}
170
171              Types:
172
173                 Name = tab_name()
174                 Key = Reason = term()
175
176              Deletes all objects with key Key from table Name.
177
178       delete_all_objects(Name) -> ok | {error, Reason}
179
180              Types:
181
182                 Name = tab_name()
183                 Reason = term()
184
185              Deletes  all  objects from a table in almost constant time. How‐
186              ever, if the table if fixed, delete_all_objects(T) is equivalent
187              to match_delete(T, '_').
188
189       delete_object(Name, Object) -> ok | {error, Reason}
190
191              Types:
192
193                 Name = tab_name()
194                 Object = object()
195                 Reason = term()
196
197              Deletes  all  instances of a specified object from a table. If a
198              table is of type bag or duplicate_bag, this function can be used
199              to delete only some of the objects with a specified key.
200
201       first(Name) -> Key | '$end_of_table'
202
203              Types:
204
205                 Name = tab_name()
206                 Key = term()
207
208              Returns  the first key stored in table Name according to the in‐
209              ternal order of the table, or '$end_of_table' if  the  table  is
210              empty.
211
212              Unless  the table is protected using safe_fixtable/2, subsequent
213              calls to next/2 do possibly not work as expected  if  concurrent
214              updates are made to the table.
215
216              If  an  error  occurs, the process is exited with an error tuple
217              {error, Reason}. The error tuple is not returned, as  it  cannot
218              be distinguished from a key.
219
220              There are two reasons why first/1 and next/2 are not to be used:
221              they are  not  efficient,  and  they  prevent  the  use  of  key
222              '$end_of_table', as this atom is used to indicate the end of the
223              table. If possible, use functions match, match_object,  and  se‐
224              lect for traversing tables.
225
226       foldl(Function, Acc0, Name) -> Acc | {error, Reason}
227
228       foldr(Function, Acc0, Name) -> Acc | {error, Reason}
229
230              Types:
231
232                 Name = tab_name()
233                 Function = fun((Object :: object(), AccIn) -> AccOut)
234                 Acc0 = Acc = AccIn = AccOut = Reason = term()
235
236              Calls  Function  on  successive  elements of table Name together
237              with an extra argument AccIn. The table elements  are  traversed
238              in  unspecified  order.  Function  must return a new accumulator
239              that is passed to the next call. Acc0 is returned if  the  table
240              is empty.
241
242       from_ets(Name, EtsTab) -> ok | {error, Reason}
243
244              Types:
245
246                 Name = tab_name()
247                 EtsTab = ets:tab()
248                 Reason = term()
249
250              Deletes  all  objects of table Name and then inserts all the ob‐
251              jects of the ETS table EtsTab. The objects are inserted  in  un‐
252              specified order. As ets:safe_fixtable/2 is called, the ETS table
253              must be public or owned by the calling process.
254
255       info(Name) -> InfoList | undefined
256
257              Types:
258
259                 Name = tab_name()
260                 InfoList = [InfoTuple]
261                 InfoTuple =
262                     {file_size, integer() >= 0} |
263                     {filename, file:name()} |
264                     {keypos, keypos()} |
265                     {size, integer() >= 0} |
266                     {type, type()}
267
268              Returns information about table Name as a list of tuples:
269
270                * {file_size, integer() >= 0}} - The file size, in bytes.
271
272                * {filename, file:name()} - The name of the file where objects
273                  are stored.
274
275                * {keypos, keypos()} - The key position.
276
277                * {size, integer() >= 0} - The number of objects stored in the
278                  table.
279
280                * {type, type()} - The table type.
281
282       info(Name, Item) -> Value | undefined
283
284              Types:
285
286                 Name = tab_name()
287                 Item =
288                     access | auto_save | bchunk_format | hash | file_size |
289                     filename | keypos |  memory  |  no_keys  |  no_objects  |
290                 no_slots |
291                     owner | ram_file | safe_fixed | safe_fixed_monotonic_time
292                 |
293                     size | type
294                 Value = term()
295
296              Returns the information associated with Item for table Name.  In
297              addition to the {Item, Value} pairs defined for info/1, the fol‐
298              lowing items are allowed:
299
300                * {access, access()} - The access mode.
301
302                * {auto_save, auto_save()} - The autosave interval.
303
304                * {bchunk_format, binary()} - An opaque binary describing  the
305                  format  of  the objects returned by bchunk/2. The binary can
306                  be used as argument to is_compatible_chunk_format/2.
307
308                * {hash, Hash} - Describes which BIF is used to calculate  the
309                  hash  values of the objects stored in the Dets table. Possi‐
310                  ble values of Hash:
311
312                  * phash - Implies that the erlang:phash/2 BIF is used.
313
314                  * phash2 - Implies that the erlang:phash2/1 BIF is used.
315
316                * {memory, integer() >= 0} - The file size, in bytes. The same
317                  value is associated with item file_size.
318
319                * {no_keys,  integer  >=  0()}  - The number of different keys
320                  stored in the table.
321
322                * {no_objects, integer >= 0()} - The number of objects  stored
323                  in the table.
324
325                * {no_slots,  {Min,  Used,  Max}} - The number of slots of the
326                  table. Min is the minimum number of slots, Used is the  num‐
327                  ber  of  currently used slots, and Max is the maximum number
328                  of slots.
329
330                * {owner, pid()} - The pid of the  process  that  handles  re‐
331                  quests to the Dets table.
332
333                * {ram_file, boolean()} - Whether the table is kept in RAM.
334
335                * {safe_fixed_monotonic_time,  SafeFixed}  -  If  the table is
336                  fixed, SafeFixed is a tuple {FixedAtTime, [{Pid,RefCount}]}.
337                  FixedAtTime  is the time when the table was first fixed, and
338                  Pid is the pid of the process that fixes the table  RefCount
339                  times.  There can be any number of processes in the list. If
340                  the table is not fixed, SafeFixed is the atom false.
341
342                  FixedAtTime  corresponds  to  the  result  returned  by  er‐
343                  lang:monotonic_time/0  at  the  time of fixation. The use of
344                  safe_fixed_monotonic_time is  time warp safe.
345
346                * {safe_fixed, SafeFixed}  -  The  same  as  {safe_fixed_mono‐
347                  tonic_time,  SafeFixed} except the format and value of Fixe‐
348                  dAtTime.
349
350                  FixedAtTime  corresponds  to  the  result  returned  by  er‐
351                  lang:timestamp/0  at  the time of fixation. Notice that when
352                  the system uses single or multi time warp  modes,  this  can
353                  produce   strange  results.  This  is  because  the  use  of
354                  safe_fixed is not  time warp safe. Time warp safe code  must
355                  use safe_fixed_monotonic_time instead.
356
357       init_table(Name, InitFun) -> ok | {error, Reason}
358
359       init_table(Name, InitFun, Options) -> ok | {error, Reason}
360
361              Types:
362
363                 Name = tab_name()
364                 InitFun = fun((Arg) -> Res)
365                 Arg = read | close
366                 Res =
367                     end_of_input |
368                     {[object()], InitFun} |
369                     {Data, InitFun} |
370                     term()
371                 Options = Option | [Option]
372                 Option = {min_no_slots, no_slots()} | {format, term | bchunk}
373                 Reason = term()
374                 Data = binary() | tuple()
375
376              Replaces the existing objects of table Name with objects created
377              by calling the input function InitFun, see below. The reason for
378              using  this function rather than calling insert/2 is that of ef‐
379              ficiency. Notice that the input  functions  are  called  by  the
380              process  that  handles  requests  to  the Dets table, not by the
381              calling process.
382
383              When called with argument read, function InitFun is  assumed  to
384              return  end_of_input  when  there is no more input, or {Objects,
385              Fun}, where Objects is a list of objects and Fun is a new  input
386              function.  Any other value Value is returned as an error {error,
387              {init_fun, Value}}. Each input function is called exactly  once,
388              and  if  an error occurs, the last function is called with argu‐
389              ment close, the reply of which is ignored.
390
391              If the table type is set and more than one object exists with  a
392              given key, one of the objects is chosen. This is not necessarily
393              the last object with the given key in the  sequence  of  objects
394              returned by the input functions. Avoid duplicate keys, otherwise
395              the file becomes unnecessarily fragmented. This holds  also  for
396              duplicated objects stored in tables of type bag.
397
398              It  is important that the table has a sufficient number of slots
399              for the objects. If not, the  hash  list  starts  to  grow  when
400              init_table/2  returns,  which significantly slows down access to
401              the table for a period of time. The minimum number of  slots  is
402              set  by  the open_file/2 option min_no_slots and returned by the
403              info/2 item no_slots. See also option min_no_slots below.
404
405              Argument Options is a list of {Key, Val} tuples, where the  fol‐
406              lowing values are allowed:
407
408                * {min_no_slots,  no_slots()} - Specifies the estimated number
409                  of different keys to be stored in the table. The open_file/2
410                  option  with  the  same name is ignored, unless the table is
411                  created, in which case performance can be enhanced  by  sup‐
412                  plying an estimate when initializing the table.
413
414                * {format,  Format}  - Specifies the format of the objects re‐
415                  turned by function InitFun. If Format is term (the default),
416                  InitFun  is assumed to return a list of tuples. If Format is
417                  bchunk, InitFun is assumed to return  Data  as  returned  by
418                  bchunk/2. This option overrides option min_no_slots.
419
420       insert(Name, Objects) -> ok | {error, Reason}
421
422              Types:
423
424                 Name = tab_name()
425                 Objects = object() | [object()]
426                 Reason = term()
427
428              Inserts  one  or  more objects into the table Name. If there al‐
429              ready exists an object with a key matching the key  of  some  of
430              the given objects and the table type is set, the old object will
431              be replaced.
432
433       insert_new(Name, Objects) -> boolean() | {error, Reason}
434
435              Types:
436
437                 Name = tab_name()
438                 Objects = object() | [object()]
439                 Reason = term()
440
441              Inserts one or more objects into table Name.  If  there  already
442              exists  some  object  with  a key matching the key of any of the
443              specified objects, the table is not updated  and  false  is  re‐
444              turned. Otherwise the objects are inserted and true returned.
445
446       is_compatible_bchunk_format(Name, BchunkFormat) -> boolean()
447
448              Types:
449
450                 Name = tab_name()
451                 BchunkFormat = binary()
452
453              Returns  true  if it would be possible to initialize table Name,
454              using init_table/3 with option {format,  bchunk},  with  objects
455              read  with bchunk/2 from some table T, such that calling info(T,
456              bchunk_format) returns BchunkFormat.
457
458       is_dets_file(Filename) -> boolean() | {error, Reason}
459
460              Types:
461
462                 Filename = file:name()
463                 Reason = term()
464
465              Returns true if file Filename is a Dets table, otherwise false.
466
467       lookup(Name, Key) -> Objects | {error, Reason}
468
469              Types:
470
471                 Name = tab_name()
472                 Key = term()
473                 Objects = [object()]
474                 Reason = term()
475
476              Returns a list of all objects with key Key stored in table Name,
477              for example:
478
479              2> dets:open_file(abc, [{type, bag}]).
480              {ok,abc}
481              3> dets:insert(abc, {1,2,3}).
482              ok
483              4> dets:insert(abc, {1,3,4}).
484              ok
485              5> dets:lookup(abc, 1).
486              [{1,2,3},{1,3,4}]
487
488              If  the table type is set, the function returns either the empty
489              list or a list with one object, as there cannot be more than one
490              object  with  a  given  key.  If the table type is bag or dupli‐
491              cate_bag, the function returns a list of arbitrary length.
492
493              Notice that the order of objects  returned  is  unspecified.  In
494              particular,  the order in which objects were inserted is not re‐
495              flected.
496
497       match(Continuation) ->
498                {[Match], Continuation2} |
499                '$end_of_table' |
500                {error, Reason}
501
502              Types:
503
504                 Continuation = Continuation2 = bindings_cont()
505                 Match = [term()]
506                 Reason = term()
507
508              Matches some objects stored in a table and returns  a  non-empty
509              list  of  the  bindings matching a specified pattern in some un‐
510              specified order. The table, the pattern, and the number  of  ob‐
511              jects  that  are  matched are all defined by Continuation, which
512              has been returned by a previous call to match/1 or match/3.
513
514              When all table objects are matched, '$end_of_table' is returned.
515
516       match(Name, Pattern) -> [Match] | {error, Reason}
517
518              Types:
519
520                 Name = tab_name()
521                 Pattern = pattern()
522                 Match = [term()]
523                 Reason = term()
524
525              Returns for each object of table Name  that  matches  Pattern  a
526              list of bindings in some unspecified order. For a description of
527              patterns, see ets:match/2. If the keypos'th element  of  Pattern
528              is unbound, all table objects are matched. If the keypos'th ele‐
529              ment is bound,  only  the  objects  with  the  correct  key  are
530              matched.
531
532       match(Name, Pattern, N) ->
533                {[Match], Continuation} |
534                '$end_of_table' |
535                {error, Reason}
536
537              Types:
538
539                 Name = tab_name()
540                 Pattern = pattern()
541                 N = default | integer() >= 0
542                 Continuation = bindings_cont()
543                 Match = [term()]
544                 Reason = term()
545
546              Matches  some  or  all  objects of table Name and returns a non-
547              empty list of the bindings that match Pattern in  some  unspeci‐
548              fied order. For a description of patterns, see ets:match/2.
549
550              A  tuple  of the bindings and a continuation is returned, unless
551              the table is empty, in which case '$end_of_table'  is  returned.
552              The  continuation is to be used when matching further objects by
553              calling match/1.
554
555              If the keypos'th element of Pattern is bound, all table  objects
556              are  matched. If the keypos'th element is unbound, all table ob‐
557              jects are matched, N objects at a time, until at least  one  ob‐
558              ject  matches  or  the end of the table is reached. The default,
559              indicated by giving N the value default, is to let the number of
560              objects  vary depending on the sizes of the objects. All objects
561              with the same key are always matched at the same time, which im‐
562              plies that more than N objects can sometimes be matched.
563
564              The table is always to be protected using safe_fixtable/2 before
565              calling  match/3,  otherwise  errors  can  occur  when   calling
566              match/1.
567
568       match_delete(Name, Pattern) -> ok | {error, Reason}
569
570              Types:
571
572                 Name = tab_name()
573                 Pattern = pattern()
574                 Reason = term()
575
576              Deletes  all  objects  that match Pattern from table Name. For a
577              description of patterns, see ets:match/2.
578
579              If the keypos'th element of Pattern is bound, only  the  objects
580              with the correct key are matched.
581
582       match_object(Continuation) ->
583                       {Objects, Continuation2} |
584                       '$end_of_table' |
585                       {error, Reason}
586
587              Types:
588
589                 Continuation = Continuation2 = object_cont()
590                 Objects = [object()]
591                 Reason = term()
592
593              Returns  a non-empty list of some objects stored in a table that
594              match a given pattern in some unspecified order. The table,  the
595              pattern,  and the number of objects that are matched are all de‐
596              fined by Continuation, which has been  returned  by  a  previous
597              call to match_object/1 or match_object/3.
598
599              When all table objects are matched, '$end_of_table' is returned.
600
601       match_object(Name, Pattern) -> Objects | {error, Reason}
602
603              Types:
604
605                 Name = tab_name()
606                 Pattern = pattern()
607                 Objects = [object()]
608                 Reason = term()
609
610              Returns  a  list of all objects of table Name that match Pattern
611              in some unspecified order. For a description  of  patterns,  see
612              ets:match/2.
613
614              If  the  keypos'th  element of Pattern is unbound, all table ob‐
615              jects are matched. If the keypos'th element of Pattern is bound,
616              only the objects with the correct key are matched.
617
618              Using  the  match_object  functions for traversing all table ob‐
619              jects is more efficient  than  calling  first/1  and  next/2  or
620              slot/2.
621
622       match_object(Name, Pattern, N) ->
623                       {Objects, Continuation} |
624                       '$end_of_table' |
625                       {error, Reason}
626
627              Types:
628
629                 Name = tab_name()
630                 Pattern = pattern()
631                 N = default | integer() >= 0
632                 Continuation = object_cont()
633                 Objects = [object()]
634                 Reason = term()
635
636              Matches  some  or all objects stored in table Name and returns a
637              non-empty list of the objects that match Pattern in some unspec‐
638              ified order. For a description of patterns, see ets:match/2.
639
640              A list of objects and a continuation is returned, unless the ta‐
641              ble is empty, in which case  '$end_of_table'  is  returned.  The
642              continuation  is  to  be  used  when matching further objects by
643              calling match_object/1.
644
645              If the keypos'th element of Pattern is bound, all table  objects
646              are  matched. If the keypos'th element is unbound, all table ob‐
647              jects are matched, N objects at a time, until at least  one  ob‐
648              ject  matches  or  the end of the table is reached. The default,
649              indicated by giving N the value default, is to let the number of
650              objects vary depending on the sizes of the objects. All matching
651              objects with the same key are always returned in the same reply,
652              which  implies  that  more  than  N objects can sometimes be re‐
653              turned.
654
655              The table is always to be protected using safe_fixtable/2 before
656              calling  match_object/3, otherwise errors can occur when calling
657              match_object/1.
658
659       member(Name, Key) -> boolean() | {error, Reason}
660
661              Types:
662
663                 Name = tab_name()
664                 Key = Reason = term()
665
666              Works like lookup/2, but does not return  the  objects.  Returns
667              true if one or more table elements has key Key, otherwise false.
668
669       next(Name, Key1) -> Key2 | '$end_of_table'
670
671              Types:
672
673                 Name = tab_name()
674                 Key1 = Key2 = term()
675
676              Returns either the key following Key1 in table Name according to
677              the internal order of the table, or '$end_of_table' if there  is
678              no next key.
679
680              If  an  error  occurs, the process is exited with an error tuple
681              {error, Reason}.
682
683              To find the first key in the table, use first/1.
684
685       open_file(Filename) -> {ok, Reference} | {error, Reason}
686
687              Types:
688
689                 Filename = file:name()
690                 Reference = reference()
691                 Reason = term()
692
693              Opens an existing table. If the table is not properly closed, it
694              is  repaired.  The returned reference is to be used as the table
695              name. This function is most useful for debugging purposes.
696
697       open_file(Name, Args) -> {ok, Name} | {error, Reason}
698
699              Types:
700
701                 Name = tab_name()
702                 Args = [OpenArg]
703                 OpenArg =
704                     {access, access()} |
705                     {auto_save, auto_save()} |
706                     {estimated_no_objects, integer() >= 0} |
707                     {file, file:name()} |
708                     {max_no_slots, no_slots()} |
709                     {min_no_slots, no_slots()} |
710                     {keypos, keypos()} |
711                     {ram_file, boolean()} |
712                     {repair, boolean() | force} |
713                     {type, type()}
714                 Reason = term()
715
716              Opens a table. An empty Dets table is created if no file exists.
717
718              The atom Name is the table name. The table name must be provided
719              in  all subsequent operations on the table. The name can be used
720              by other processes as well, and many processes can share one ta‐
721              ble.
722
723              If two processes open the same table by giving the same name and
724              arguments, the table has two users. If one user closes  the  ta‐
725              ble, it remains open until the second user closes it.
726
727              Argument  Args is a list of {Key, Val} tuples, where the follow‐
728              ing values are allowed:
729
730                * {access, access()} - Existing tables can be opened in  read-
731                  only  mode.  A table that is opened in read-only mode is not
732                  subjected to the automatic file reparation algorithm  if  it
733                  is later opened after a crash. Defaults to read_write.
734
735                * {auto_save, auto_save()} - The autosave interval. If the in‐
736                  terval is an integer Time, the  table  is  flushed  to  disk
737                  whenever  it  is not accessed for Time milliseconds. A table
738                  that has been flushed requires no reparation  when  reopened
739                  after  an uncontrolled emulator halt. If the interval is the
740                  atom infinity, autosave is disabled. Defaults to  180000  (3
741                  minutes).
742
743                * {estimated_no_objects,  no_slots()}  -  Equivalent to option
744                  min_no_slots.
745
746                * {file, file:name()} - The name of the file to be opened. De‐
747                  faults to the table name.
748
749                * {max_no_slots,  no_slots()} - The maximum number of slots to
750                  be used. Defaults to 32 M, which is the maximal  value.  No‐
751                  tice  that  a higher value can increase the table fragmenta‐
752                  tion, and a smaller value can decrease the fragmentation, at
753                  the expense of execution time.
754
755                * {min_no_slots,  no_slots()} - Application performance can be
756                  enhanced with this flag by specifying,  when  the  table  is
757                  created, the estimated number of different keys to be stored
758                  in the table. Defaults to 256, which is the minimum value.
759
760                * {keypos, keypos()} - The position of the element of each ob‐
761                  ject  to  be  used as key. Defaults to 1. The ability to ex‐
762                  plicitly state the key position is most convenient  when  we
763                  want  to store Erlang records in which the first position of
764                  the record is the name of the record type.
765
766                * {ram_file, boolean()} - Whether the table is to be  kept  in
767                  RAM. Keeping the table in RAM can sound like an anomaly, but
768                  can enhance the performance of applications that open a  ta‐
769                  ble, insert a set of objects, and then close the table. When
770                  the table is closed, its contents are written  to  the  disk
771                  file. Defaults to false.
772
773                * {repair,  Value}  -  Value  can be either a boolean() or the
774                  atom force. The flag specifies if the Dets server is to  in‐
775                  voke  the  automatic  file reparation algorithm. Defaults to
776                  true. If false is specified, no attempt is  made  to  repair
777                  the  file, and {error, {needs_repair, FileName}} is returned
778                  if the table must be repaired.
779
780                  Value force means that a reparation is made even if the  ta‐
781                  ble is properly closed. This is a seldom needed option.
782
783                  Option repair is ignored if the table is already open.
784
785                * {type, type()} - The table type. Defaults to set.
786
787       pid2name(Pid) -> {ok, Name} | undefined
788
789              Types:
790
791                 Pid = pid()
792                 Name = tab_name()
793
794              Returns  the  table name given the pid of a process that handles
795              requests to a table, or undefined if there is no such table.
796
797              This function is meant to be used for debugging only.
798
799       repair_continuation(Continuation, MatchSpec) -> Continuation2
800
801              Types:
802
803                 Continuation = Continuation2 = select_cont()
804                 MatchSpec = match_spec()
805
806              This function can be used to restore an opaque continuation  re‐
807              turned  by  select/3  or select/1 if the continuation has passed
808              through external term format (been sent between nodes or  stored
809              on disk).
810
811              The  reason for this function is that continuation terms contain
812              compiled match specifications and therefore are  invalidated  if
813              converted to external term format. Given that the original match
814              specification is kept intact, the continuation can be  restored,
815              meaning  it  can once again be used in subsequent select/1 calls
816              even though it has been stored on disk or on another node.
817
818              For more information and examples, see the ets(3) module.
819
820          Note:
821              This function is rarely needed in application code. It  is  used
822              by  application  Mnesia  to provide distributed select/3 and se‐
823              lect/1 sequences. A normal application would either  use  Mnesia
824              or  keep  the continuation from being converted to external for‐
825              mat.
826
827              The reason for not having an external representation of compiled
828              match specifications is performance. It can be subject to change
829              in future releases, while this interface  remains  for  backward
830              compatibility.
831
832
833       safe_fixtable(Name, Fix) -> ok
834
835              Types:
836
837                 Name = tab_name()
838                 Fix = boolean()
839
840              If  Fix  is true, table Name is fixed (once more) by the calling
841              process, otherwise the table is released. The table is also  re‐
842              leased when a fixing process terminates.
843
844              If many processes fix a table, the table remains fixed until all
845              processes have released it or terminated. A reference counter is
846              kept  on  a per process basis, and N consecutive fixes require N
847              releases to release the table.
848
849              It is not guaranteed that calls to first/1,  next/2,  or  select
850              and match functions work as expected even if the table is fixed;
851              the limited support for concurrency provided by the ets(3)  mod‐
852              ule  is  not yet provided by Dets. Fixing a table currently only
853              disables resizing of the hash list of the table.
854
855              If objects have been added while the table was fixed,  the  hash
856              list  starts  to grow when the table is released, which signifi‐
857              cantly slows down access to the table for a period of time.
858
859       select(Continuation) ->
860                 {Selection, Continuation2} |
861                 '$end_of_table' |
862                 {error, Reason}
863
864              Types:
865
866                 Continuation = Continuation2 = select_cont()
867                 Selection = [term()]
868                 Reason = term()
869
870              Applies a match specification to some objects stored in a  table
871              and  returns  a  non-empty  list  of the results. The table, the
872              match specification, and the number of objects that are  matched
873              are all defined by Continuation, which is returned by a previous
874              call to select/1 or select/3.
875
876              When all objects of the table have been matched, '$end_of_table'
877              is returned.
878
879       select(Name, MatchSpec) -> Selection | {error, Reason}
880
881              Types:
882
883                 Name = tab_name()
884                 MatchSpec = match_spec()
885                 Selection = [term()]
886                 Reason = term()
887
888              Returns the results of applying match specification MatchSpec to
889              all or some objects stored in table Name. The order of  the  ob‐
890              jects  is  not  specified. For a description of match specifica‐
891              tions, see the ERTS User's Guide.
892
893              If the keypos'th element of  MatchSpec  is  unbound,  the  match
894              specification  is  applied  to  all objects of the table. If the
895              keypos'th element is bound, the match specification  is  applied
896              to the objects with the correct key(s) only.
897
898              Using the select functions for traversing all objects of a table
899              is more efficient than calling first/1 and next/2 or slot/2.
900
901       select(Name, MatchSpec, N) ->
902                 {Selection, Continuation} |
903                 '$end_of_table' |
904                 {error, Reason}
905
906              Types:
907
908                 Name = tab_name()
909                 MatchSpec = match_spec()
910                 N = default | integer() >= 0
911                 Continuation = select_cont()
912                 Selection = [term()]
913                 Reason = term()
914
915              Returns the results of applying match specification MatchSpec to
916              some  or  all objects stored in table Name. The order of the ob‐
917              jects is not specified. For a description  of  match  specifica‐
918              tions, see the ERTS User's Guide.
919
920              A tuple of the results of applying the match specification and a
921              continuation is returned, unless the table is  empty,  in  which
922              case '$end_of_table' is returned. The continuation is to be used
923              when matching more objects by calling select/1.
924
925              If the keypos'th element of MatchSpec is bound, the match speci‐
926              fication is applied to all objects of the table with the correct
927              key(s). If the keypos'th element of MatchSpec  is  unbound,  the
928              match  specification  is  applied to all objects of the table, N
929              objects at a time, until at least one object matches or the  end
930              of  the table is reached. The default, indicated by giving N the
931              value default, is to let the number of objects vary depending on
932              the  sizes of the objects. All objects with the same key are al‐
933              ways handled at the same time,  which  implies  that  the  match
934              specification can be applied to more than N objects.
935
936              The table is always to be protected using safe_fixtable/2 before
937              calling select/3, otherwise errors can occur  when  calling  se‐
938              lect/1.
939
940       select_delete(Name, MatchSpec) -> N | {error, Reason}
941
942              Types:
943
944                 Name = tab_name()
945                 MatchSpec = match_spec()
946                 N = integer() >= 0
947                 Reason = term()
948
949              Deletes  each  object  from  table Name such that applying match
950              specification MatchSpec to the object returns value true. For  a
951              description  of match specifications, see the ERTS User's Guide.
952              Returns the number of deleted objects.
953
954              If the keypos'th element of MatchSpec is bound, the match speci‐
955              fication is applied to the objects with the correct key(s) only.
956
957       slot(Name, I) -> '$end_of_table' | Objects | {error, Reason}
958
959              Types:
960
961                 Name = tab_name()
962                 I = integer() >= 0
963                 Objects = [object()]
964                 Reason = term()
965
966              The  objects  of  a  table are distributed among slots, starting
967              with slot 0 and ending with slot n. Returns the list of  objects
968              associated with slot I. If I > n, '$end_of_table' is returned.
969
970       sync(Name) -> ok | {error, Reason}
971
972              Types:
973
974                 Name = tab_name()
975                 Reason = term()
976
977              Ensures that all updates made to table Name are written to disk.
978              This also applies to tables that  have  been  opened  with  flag
979              ram_file set to true. In this case, the contents of the RAM file
980              are flushed to disk.
981
982              Notice that the space management data structures  kept  in  RAM,
983              the  buddy  system,  is  also written to the disk. This can take
984              some time if the table is fragmented.
985
986       table(Name) -> QueryHandle
987
988       table(Name, Options) -> QueryHandle
989
990              Types:
991
992                 Name = tab_name()
993                 Options = Option | [Option]
994                 Option = {n_objects, Limit} | {traverse, TraverseMethod}
995                 Limit = default | integer() >= 1
996                 TraverseMethod = first_next | select | {select, match_spec()}
997                 QueryHandle = qlc:query_handle()
998
999              Returns a Query  List  Comprehension  (QLC)  query  handle.  The
1000              qlc(3) module provides a query language aimed mainly for Mnesia,
1001              but ETS tables, Dets tables, and lists are  also  recognized  by
1002              qlc  as  sources of data. Calling dets:table/1,2 is the means to
1003              make Dets table Name usable to qlc.
1004
1005              When there are only simple restrictions on the key position, qlc
1006              uses  dets:lookup/2 to look up the keys. When that is not possi‐
1007              ble, the whole table is traversed.  Option  traverse  determines
1008              how this is done:
1009
1010                * first_next  -  The  table  is traversed one key at a time by
1011                  calling dets:first/1 and dets:next/2.
1012
1013                * select - The table is traversed by calling dets:select/3 and
1014                  dets:select/1. Option n_objects determines the number of ob‐
1015                  jects returned (the third argument of select/3).  The  match
1016                  specification (the second argument of select/3) is assembled
1017                  by qlc:
1018
1019                  * Simple filters are translated into equivalent match speci‐
1020                    fications.
1021
1022                  * More  complicated  filters  must be applied to all objects
1023                    returned by select/3  given  a  match  specification  that
1024                    matches all objects.
1025
1026                * {select,    match_spec()} - As for select, the table is tra‐
1027                  versed by calling dets:select/3 and dets:select/1. The  dif‐
1028                  ference is that the match specification is specified explic‐
1029                  itly. This is how to state match specifications that  cannot
1030                  easily be expressed within the syntax provided by qlc.
1031
1032              The  following  example  uses an explicit match specification to
1033              traverse the table:
1034
1035              1> dets:open_file(t, []),
1036              ok = dets:insert(t, [{1,a},{2,b},{3,c},{4,d}]),
1037              MS = ets:fun2ms(fun({X,Y}) when (X > 1) or (X < 5) -> {Y} end),
1038              QH1 = dets:table(t, [{traverse, {select, MS}}]).
1039
1040              An example with implicit match specification:
1041
1042              2> QH2 = qlc:q([{Y} || {X,Y} <- dets:table(t), (X > 1) or (X < 5)]).
1043
1044              The latter example is equivalent to the  former,  which  can  be
1045              verified using function qlc:info/1:
1046
1047              3> qlc:info(QH1) =:= qlc:info(QH2).
1048              true
1049
1050              qlc:info/1  returns  information  about  a query handle. In this
1051              case identical information is returned for the  two  query  han‐
1052              dles.
1053
1054       to_ets(Name, EtsTab) -> EtsTab | {error, Reason}
1055
1056              Types:
1057
1058                 Name = tab_name()
1059                 EtsTab = ets:tab()
1060                 Reason = term()
1061
1062              Inserts  the  objects  of the Dets table Name into the ETS table
1063              EtsTab. The order in which the objects are inserted is not spec‐
1064              ified.  The  existing  objects  of the ETS table are kept unless
1065              overwritten.
1066
1067       traverse(Name, Fun) -> Return | {error, Reason}
1068
1069              Types:
1070
1071                 Name = tab_name()
1072                 Fun = fun((Object) -> FunReturn)
1073                 Object = object()
1074                 FunReturn =
1075                     continue | {continue, Val} | {done, Value} | OtherValue
1076                 Return = [term()] | OtherValue
1077                 Val = Value = OtherValue = Reason = term()
1078
1079              Applies Fun to each object stored in table Name in some unspeci‐
1080              fied  order. Different actions are taken depending on the return
1081              value of Fun. The following Fun return values are allowed:
1082
1083                continue:
1084                  Continue to perform the traversal. For example, the  follow‐
1085                  ing function can be used to print the contents of a table:
1086
1087                fun(X) -> io:format("~p~n", [X]), continue end.
1088
1089                {continue, Val}:
1090                  Continue  the  traversal  and  accumulate Val. The following
1091                  function is supplied to collect all objects of a table in  a
1092                  list:
1093
1094                fun(X) -> {continue, X} end.
1095
1096                {done, Value}:
1097                  Terminate the traversal and return [Value | Acc].
1098
1099              Any  other  value OtherValue returned by Fun terminates the tra‐
1100              versal and is returned immediately.
1101
1102       update_counter(Name, Key, Increment) -> Result
1103
1104              Types:
1105
1106                 Name = tab_name()
1107                 Key = term()
1108                 Increment = {Pos, Incr} | Incr
1109                 Pos = Incr = Result = integer()
1110
1111              Updates the object with key Key stored in table Name of type set
1112              by  adding  Incr  to the element at the Pos:th position. The new
1113              counter value is returned. If no position is specified, the ele‐
1114              ment directly following the key is updated.
1115
1116              This  functions  provides  a  way of updating a counter, without
1117              having to look up an object, update the object  by  incrementing
1118              an  element,  and  insert  the  resulting  object into the table
1119              again.
1120

SEE ALSO

1122       ets(3), mnesia(3), qlc(3)
1123
1124
1125
1126Ericsson AB                      stdlib 3.17.2                         dets(3)
Impressum