doc/user/tutorials/tutorial-keep.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Storing and Retrieving data using Keep"
   5 ...
   6
   7 This tutorial introduces you to the Arvados file storage system.
   8
   9 {% include 'tutorial_expectations' %}
  10
  11 The Arvados distributed file system is called *Keep*.  Keep is a content-addressable file system.  This means that files are managed using special unique identifiers derived from the _contents_ of the file, rather than human-assigned file names (specifically, the MD5 hash).  This has a number of advantages:
  12 * Files can be stored and replicated across a cluster of servers without requiring a central name server.
  13 * Both the server and client systematically validate data integrity because the checksum is built into the identifier.
  14 * Data duplication is minimized—two files with the same contents will have in the same identifier, and will not be stored twice.
  15 * It avoids data race conditions, since an identifier always points to the same data.
  16
  17 h1. Putting Data into Keep
  18
  19 We will start by downloading a freely available VCF file from "Personal Genome Project (PGP)":http://www.personalgenomes.org subject "hu599905":https://my.personalgenomes.org/profile/hu599905 to a staging directory on the VM, and adding it to Keep.  In the following commands, replace *@you@* with your login name.
  20
  21 First, log into your Arvados VM and set up the staging area:
  22
  23 notextile. <pre><code>~$ <span class="userinput">mkdir /scratch/<b>you</b></span></code></pre>
  24
  25 Next, download the file:
  26
  27 <notextile>
  28 <pre><code>~$ <span class="userinput">cd /scratch/<b>you</b></span>
  29 /scratch/<b>you</b>$ <span class="userinput">curl -o var-GS000016015-ASM.tsv.bz2 'https://warehouse.personalgenomes.org/warehouse/f815ec01d5d2f11cb12874ab2ed50daa+234+K@ant/var-GS000016015-ASM.tsv.bz2'</span>
  30   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
  31                                  Dload  Upload   Total   Spent    Left  Speed
  32 100  216M  100  216M    0     0  10.0M      0  0:00:21  0:00:21 --:--:-- 9361k
  33 </code></pre>
  34 </notextile>
  35
  36 {% include 'notebox_begin' %}
  37
  38 If you have your own data, for example @MyData.vcf@, you can use @scp@ or @rsync@ to copy from your local workstation to the shell VM (run this on your local workstation):
  39
  40 notextile. <pre><code>~$ <span class="userinput">scp MyData.vcf <b>you@shell</b>.arvados:/scratch/<b>you</b>/MyData.vcf</span></code></pre>
  41
  42 {% include 'notebox_end' %}
  43
  44 Now use @arv keep put@ to add your VCF data to Keep, then delete the local copy of the file:
  45
  46 <notextile>
  47 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep put var-GS000016015-ASM.tsv.bz2</span>
  48 c1bad4b39ca5a924e481008009d94e32+210
  49 /scratch/<b>you</b>$ <span class="userinput">rm var-GS000016015-ASM.tsv.bz2</span>
  50 </code></pre>
  51 </notextile>
  52
  53 The output value @c1bad4b39ca5a924e481008009d94e32+210@ from @arv keep put@ is the Keep locator.  This enables you to access the file you just uploaded, and is explained in the next section.
  54
  55 h2(#dir). Putting a directory
  56
  57 You can also use @arv keep put@ to add an entire directory:
  58
  59 <notextile>
  60 <pre><code>/scratch/<b>you</b>$ <span class="userinput">mkdir tmp</span>
  61 /scratch/<b>you</b>$ <span class="userinput">echo "hello alice" > tmp/alice.txt</span>
  62 /scratch/<b>you</b>$ <span class="userinput">echo "hello bob" > tmp/bob.txt</span>
  63 /scratch/<b>you</b>$ <span class="userinput">echo "hello carol" > tmp/carol.txt</span>
  64 /scratch/<b>you</b>$ <span class="userinput">arv keep put tmp</span>
  65 0M / 0M 100.0%
  66 887cd41e9c613463eab2f0d885c6dd96+83
  67 </code></pre>
  68 </notextile>
  69
  70 The locator @887cd41e9c613463eab2f0d885c6dd96+83@ represents a collection with multiple files.
  71
  72 h1. Getting Data from Keep
  73
  74 h2. Using Workbench
  75
  76 You may access collections through the "Collections section of Arvados Workbench":https://{{ site.arvados_workbench_host }}/collections at *Data* %(rarr)&rarr;% *Collections (data files)*.  You can also access individual files within a collection.  Some examples:
  77
  78 * "https://{{ site.arvados_workbench_host }}/collections/c1bad4b39ca5a924e481008009d94e32+210":https://{{ site.arvados_workbench_host }}/collections/c1bad4b39ca5a924e481008009d94e32+210
  79 * "https://{{ site.arvados_workbench_host }}/collections/887cd41e9c613463eab2f0d885c6dd96+83/alice.txt":https://{{ site.arvados_workbench_host }}/collections/887cd41e9c613463eab2f0d885c6dd96+83/alice.txt
  80
  81 h2(#arv-get). Using the command line
  82
  83 You can view the contents of a collection using @arv keep ls@:
  84
  85 <notextile>
  86 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep ls c1bad4b39ca5a924e481008009d94e32+210</span>
  87 var-GS000016015-ASM.tsv.bz2
  88 </code></pre>
  89
  90 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep ls 887cd41e9c613463eab2f0d885c6dd96+83</span>
  91 alice.txt
  92 bob.txt
  93 carol.txt
  94 </code></pre>
  95 </notextile>
  96
  97 Use @-s@ to print file sizes rounded up to the nearest kilobyte:
  98
  99 <notextile>
 100 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep ls -s c1bad4b39ca5a924e481008009d94e32+210</span>
 101 221887 var-GS000016015-ASM.tsv.bz2
 102 </code></pre>
 103 </notextile>
 104
 105 Use @arv keep get@ to download the contents of a collection and place it in the directory specified in the second argument (in this example, @.@ for the current directory):
 106
 107 <notextile>
 108 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep get c1bad4b39ca5a924e481008009d94e32+210/ .</span>
 109 /scratch/<b>you</b>$ <span class="userinput">ls var-GS000016015-ASM.tsv.bz2</span>
 110 var-GS000016015-ASM.tsv.bz2
 111 </code></pre>
 112 </notextile>
 113
 114 You can also download individual files:
 115
 116 <notextile>
 117 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep get 887cd41e9c613463eab2f0d885c6dd96+83/alice.txt .</span>
 118 </code></pre>
 119 </notextile>
 120
 121 With a local copy of the file, we can do some computation, for example computing the MD5 hash of the complete file:
 122
 123 <notextile>
 124 <pre><code>/scratch/<b>you</b>$ <span class="userinput">md5sum var-GS000016015-ASM.tsv.bz2</span>
 125 44b8ae3fde7a8a88d2f7ebd237625b4f  var-GS000016015-ASM.tsv.bz2
 126 </code></pre>
 127 </notextile>
 128
 129 h2. Using arv-mount
 130
 131 Use @arv-mount@ to mount a Keep collection and access it using traditional filesystem tools.
 132
 133 <notextile>
 134 <pre><code>/scratch/<b>you</b>$ <span class="userinput">mkdir -p mnt</span>
 135 /scratch/<b>you</b>$ <span class="userinput">arv-mount --collection c1bad4b39ca5a924e481008009d94e32+210 mnt &</span>
 136 /scratch/<b>you</b>$ <span class="userinput">cd mnt</span>
 137 /scratch/<b>you</b>/mnt$ <span class="userinput">ls</span>
 138 var-GS000016015-ASM.tsv.bz2
 139 /scratch/<b>you</b>/mnt$ <span class="userinput">md5sum var-GS000016015-ASM.tsv.bz2</span>
 140 44b8ae3fde7a8a88d2f7ebd237625b4f  var-GS000016015-ASM.tsv.bz2
 141 /scratch/<b>you</b>/mnt$ <span class="userinput">cd ..</span>
 142 /scratch/<b>you</b>$ <span class="userinput">fusermount -u mnt</span>
 143 </code></pre>
 144 </notextile>
 145
 146 You can also mount the entire Keep namespace in "magic directory" mode:
 147
 148 <notextile>
 149 <pre><code>/scratch/<b>you</b>$ <span class="userinput">mkdir -p mnt</span>
 150 /scratch/<b>you</b>$ <span class="userinput">arv-mount mnt &</span>
 151 /scratch/<b>you</b>$ <span class="userinput">cd mnt/c1bad4b39ca5a924e481008009d94e32+210</span>
 152 /scratch/<b>you</b>/mnt/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">ls</span>
 153 var-GS000016015-ASM.tsv.bz2
 154 /scratch/<b>you</b>/mnt/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">md5sum var-GS000016015-ASM.tsv.bz2</span>
 155 44b8ae3fde7a8a88d2f7ebd237625b4f  var-GS000016015-ASM.tsv.bz2
 156 /scratch/<b>you</b>/mnt/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">cd ../..</span>
 157 /scratch/<b>you</b>$ <span class="userinput">fusermount -u mnt</span>
 158 </code></pre>
 159 </notextile>
 160
 161 @arv-mount@ provides several features:
 162
 163 * You can browse, open and read Keep entries as if they are regular files.
 164 * It is easy for existing tools to access files in Keep.
 165 * Data is downloaded on demand.  It is not necessary to download an entire file or collection to start processing.