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

   1 ---
   2 layout: default
   3 navsection: userguide
   4 navmenu: Tutorials
   5 title: "Storing and Retrieving data using Keep"
   6 ...
   7
   8 h1. Storing and Retrieving data using Keep
   9
  10 This tutorial introduces you to the Arvados file storage system.
  11
  12
  13 *This tutorial assumes that you are "logged into an Arvados VM instance":{{site.baseurl}}/user/getting_started/ssh-access.html#login, and have a "working environment.":{{site.baseurl}}/user/getting_started/check-environment.html*
  14
  15 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:
  16 * Files can be stored and replicated across a cluster of servers without requiring a central name server.
  17 * Systematic validation of data integrity by both server and client because the checksum is built into the identifier.
  18 * Minimizes data duplication (two files with the same contents will result in the same identifier, and will not be stored twice.)
  19 * Avoids data race conditions (an identifier always points to the same data.)
  20
  21 h1. Putting Data into Keep
  22
  23 We will start with downloading a freely available VCF file from the "Personal Genome Project (PGP)":http://www.personalgenomes.org subject "hu599905":https://my.personalgenomes.org/profile/hu599905 to a staging directory on the VM, and then add it to Keep.
  24
  25 In the following tutorials, replace <b><code>you</code></b> with your user id.
  26
  27 First, log into the Arvados VM instance and set up the staging area:
  28
  29 notextile. <pre><code>~$ <span class="userinput">mkdir /scratch/<b>you</b></span></code></pre>
  30
  31 Next, download the file:
  32
  33 <notextile>
  34 <pre><code>~$ <span class="userinput">cd /scratch/<b>you</b></span>
  35 /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>
  36   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
  37                                  Dload  Upload   Total   Spent    Left  Speed
  38 100  216M  100  216M    0     0  10.0M      0  0:00:21  0:00:21 --:--:-- 9361k
  39 </code></pre>
  40 </notextile>
  41
  42 {% include 'notebox_begin' %}
  43
  44 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):
  45
  46 notextile. <pre><code>~$ <span class="userinput">scp MyData.vcf <b>you@shell</b>.arvados:/scratch/<b>you</b>/MyData.vcf</span></code></pre>
  47
  48 {% include 'notebox_end' %}
  49
  50 Now use @arv keep put@ to add your VCF data to Keep, then delete the local copy of the file:
  51
  52 <notextile>
  53 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep put var-GS000016015-ASM.tsv.bz2</span>
  54 c1bad4b39ca5a924e481008009d94e32+210
  55 /scratch/<b>you</b>$ <span class="userinput">rm var-GS000016015-ASM.tsv.bz2</span>
  56 </code></pre>
  57 </notextile>
  58
  59 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.
  60
  61 h2. Putting a directory
  62
  63 You can also use @arv keep put@ to add an entire directory:
  64
  65 <notextile>
  66 <pre><code>/scratch/<b>you</b>$ <span class="userinput">mkdir tmp</span>
  67 /scratch/<b>you</b>$ <span class="userinput">echo "hello alice" > tmp/alice.txt</span>
  68 /scratch/<b>you</b>$ <span class="userinput">echo "hello bob" > tmp/bob.txt</span>
  69 /scratch/<b>you</b>$ <span class="userinput">echo "hello carol" > tmp/carol.txt</span>
  70 /scratch/<b>you</b>$ <span class="userinput">arv keep put tmp</span>
  71 0M / 0M 100.0%
  72 887cd41e9c613463eab2f0d885c6dd96+83
  73 </code></pre>
  74 </notextile>
  75
  76 The locator @887cd41e9c613463eab2f0d885c6dd96+83@ represents a collection with multiple files.
  77
  78 h1. Getting Data from Keep
  79
  80 h2. Using Workbench
  81
  82 You may access collections through the "Collections section of Arvados Workbench":https://{{ site.arvados_workbench_host }}/collections located at "https://{{ site.arvados_workbench_host }}/collections":https://{{ site.arvados_workbench_host }}/collections .  You can also access individual collections and individual files within a collection.  Some examples:
  83
  84 * "https://{{ site.arvados_workbench_host }}/collections/c1bad4b39ca5a924e481008009d94e32+210":https://{{ site.arvados_workbench_host }}/collections/c1bad4b39ca5a924e481008009d94e32+210
  85 * "https://{{ site.arvados_workbench_host }}/collections/887cd41e9c613463eab2f0d885c6dd96+83/alice.txt":https://{{ site.arvados_workbench_host }}/collections/887cd41e9c613463eab2f0d885c6dd96+83/alice.txt
  86
  87 h2. Using arv-get
  88
  89 You can view the contents of a collection using @arv keep ls@:
  90
  91 <notextile>
  92 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep ls c1bad4b39ca5a924e481008009d94e32+210</span>
  93 var-GS000016015-ASM.tsv.bz2
  94 </code></pre>
  95
  96 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep ls 887cd41e9c613463eab2f0d885c6dd96+83</span>
  97 alice.txt
  98 bob.txt
  99 carol.txt
 100 </code></pre>
 101 </notextile>
 102
 103 Use @-s@ to print file sizes rounded up to the nearest kilobyte:
 104
 105 <notextile>
 106 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep ls -s c1bad4b39ca5a924e481008009d94e32+210</span>
 107 221887 var-GS000016015-ASM.tsv.bz2
 108 </code></pre>
 109 </notextile>
 110
 111 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):
 112
 113 <notextile>
 114 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep get c1bad4b39ca5a924e481008009d94e32+210/ .</span>
 115 </code></pre>
 116 </notextile>
 117
 118 You can also download indvidual files:
 119
 120 <notextile>
 121 <pre><code>/scratch/<b>you</b>$ <span class="userinput">arv keep get 887cd41e9c613463eab2f0d885c6dd96+83/alice.txt .</span>
 122 </code></pre>
 123 </notextile>
 124
 125 With a local copy of the file, we can do some computation, for example computing the md5 hash of the complete file:
 126
 127 <notextile>
 128 <pre><code>/scratch/<b>you</b>$ <span class="userinput">md5sum var-GS000016015-ASM.tsv.bz2</span>
 129 44b8ae3fde7a8a88d2f7ebd237625b4f  var-GS000016015-ASM.tsv.bz2
 130 </code></pre>
 131 </notextile>
 132
 133 h2. Using arv-mount
 134
 135 Use @arv-mount@ to take advantage of the "File System in User Space / FUSE":http://fuse.sourceforge.net/ feature of the Linux kernel to mount a Keep collection as if it were a regular directory tree.
 136
 137 <notextile>
 138 <pre><code>/scratch/<b>you</b>$ <span class="userinput">mkdir mnt</span>
 139 /scratch/<b>you</b>$ <span class="userinput">arv-mount --collection c1bad4b39ca5a924e481008009d94e32+210 mnt &</span>
 140 /scratch/<b>you</b>$ <span class="userinput">cd mnt</span>
 141 /scratch/<b>you</b>/mnt$ <span class="userinput">ls</span>
 142 var-GS000016015-ASM.tsv.bz2
 143 /scratch/<b>you</b>/mnt$ <span class="userinput">md5sum var-GS000016015-ASM.tsv.bz2</span>
 144 44b8ae3fde7a8a88d2f7ebd237625b4f  var-GS000016015-ASM.tsv.bz2
 145 /scratch/<b>you</b>/mnt$ <span class="userinput">cd ..</span>
 146 /scratch/<b>you</b>$ <span class="userinput">fusermount -u mnt</span>
 147 </code></pre>
 148 </notextile>
 149
 150 You can also mount the entire Keep namespace in "magic directory" mode:
 151
 152 <notextile>
 153 <pre><code>/scratch/<b>you</b>$ <span class="userinput">mkdir mnt</span>
 154 /scratch/<b>you</b>$ <span class="userinput">arv-mount mnt &</span>
 155 /scratch/<b>you</b>$ <span class="userinput">cd mnt/c1bad4b39ca5a924e481008009d94e32+210</span>
 156 /scratch/<b>you</b>/mnt/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">ls</span>
 157 var-GS000016015-ASM.tsv.bz2
 158 /scratch/<b>you</b>/mnt/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">md5sum var-GS000016015-ASM.tsv.bz2</span>
 159 44b8ae3fde7a8a88d2f7ebd237625b4f  var-GS000016015-ASM.tsv.bz2
 160 /scratch/<b>you</b>/mnt/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">cd ../..</span>
 161 /scratch/<b>you</b>$ <span class="userinput">fusermount -u mnt</span>
 162 </code></pre>
 163 </notextile>
 164
 165 Using @arv-mount@ has several significant benefits:
 166
 167 * You can browse, open and read Keep entries as if they are regular files.
 168 * It is easy for existing tools to access files in Keep.
 169 * Data is downloaded on demand, it is not necessary to download an entire file or collection to start processing
 170
 171 <hr>
 172
 173 You are now ready to proceed to the next tutorial, "running a crunch job.":tutorial-job1.html