Table of Content

Quick Start

1. Create Volume & Mount

First prepare the mount point, an empty folder/directory: 
% mkdir Alpha/
and then the magick shall begin: 
% metafs alpha Alpha/
and from this moment on, volume alpha was created (/var/lib/metafs/volumes/alpha) and appears under Alpha/.

Once you are finished playing with MetaFS call metafs -u alpha or metafs -u Alpha/ to unmount volume alpha again; sudo umount Alpha/ also works.

2. Enter MetaFS Mount

% cd Alpha/
and then populate your MetaFS at Alpha/: 
% wget http://metafs.org/DL/sample-data.tar.gz

% tar xfvz sample-data.tar.gz
once data is in the MetaFS realm, all data is indexed within seconds (it may take longer if large quantity of new data arrives), as next you can query the indexed data.

3. Find Things

For example, list all files where 'sherlock' was found (.txt, .pdf, .odt, .doc etc), by default in 
% mfind sherlock
name:
   The Memoirs of Sherlock Holmes by Arthur Conan Doyle.odt
fts:
   A Study in Scarlet (1886) Canon Doyle.pdf
   The Sign of the Four (raw).txt
   The Hound of the Baskervilles [Arthur Conan Doyle].txt
   The Memoirs of Sherlock Holmes by Arthur Conan Doyle.odt
   ...
You can also search using regular expression, and for a particular key: 
% mfind -e 'name:Sherlock'
name:
   The Memoirs of Sherlock Holmes by Arthur Conan Doyle.odt
   ...
or use /term/ which considers it as regular expression (same as -e), with additional i behind is sets case insensitivity, same as -i: 
% mfind name:/sherlock/i
name:
   The Memoirs of Sherlock Holmes by Arthur Conan Doyle.odt
   ...
Finding other metadata keys:

% mfind type:folder
type:
   DIR/
      type: folder

% mfind 'mime:image/*'
mime:
   20130914_140844.jpg
      mime: image/jpeg
   open-source-logo.png
      mime: image/x-png
   violet_sunset.jpg
      mime: image/jpeg

% mfind mime:text/html
mime:
   CC.html
      mime: text/html
      
% mfind tags:red
tags:
   violet_sunset.jpg
      tags: [ meadow, blue, red ]

List all items (e.g. photos) with near GPS location, indirect by naming the next larger city: 

% mfind location:Zurich
location:
   20121009_102859.jpg
   20121009_110113.jpg
   ...
or direct with GPS coordinates: 
% mfind location:lat=47.3,long=8.55
location:
   20121009_102859.jpg
   20121009_110113.jpg
   ...

list all items (e.g. photos) of a certain location, defined with more specifics like additional country (required to avoid ambiguities) and search distance (common abbreviations supported: m, km, mi, ft, etc), the -v gives more details: 

% mfind -v location:Paris
lookup 'Paris' () -> lat=48.85341,long=2.3488
search at lat=48.85341,long=2.3488 with dist 10,000m
   Photos/837080_orig.jpg
        location: { 
           city: Paris
           country: FR
           elevation: 42 m
           lat: 48.85341 deg
           long: 2.3488 deg
        }

% mfind -v location:city=Paris,country=US,dist=30mi
lookup 'Paris' (US) -> lat=33.66094,long=-95.55551
search at lat=33.66094,long=-95.55551 with dist 48,280.200000m
total 0 entry found (8ms 800us)
find black & white images (bw, or gray, monochrome, limited, full): 
% mfind image.color.type:bw
or images with predominant red (or yellow, orange, cyan, green, blue, violet, magenta, white, black, gray, transparent): 
% mfind 'image.theme.red>50%'
image.theme.red:
   Wallpapers/250 Amazing Landscapes Wallpapers/(104).jpg
        image.theme.red: 67.13%
   Wallpapers/250 Amazing Landscapes Wallpapers/(106).jpg
        image.theme.red: 64.00%
   Wallpapers/250 Amazing Landscapes Wallpapers/(110).jpg
        image.theme.red: 57.95%
   Wallpapers/250 Amazing Landscapes Wallpapers/(135).jpg
        image.theme.red: 52.42%
   Wallpapers/250 Amazing Landscapes Wallpapers/(172).jpg
        image.theme.red: 52.69%
   Wallpapers/250 Amazing Landscapes Wallpapers/(173).jpg
        image.theme.red: 54.87%
   Wallpapers/250 Amazing Landscapes Wallpapers/(187).jpg
        image.theme.red: 72.58%
   Wallpapers/250 Amazing Landscapes Wallpapers/(240).jpg
        image.theme.red: 53.85%
   Art/200 Leonardo da Vinci Artworks/116.jpg
   ...

or images with a certain width: 

% mfind image.width:640..1024
or minimum of 5M pixels: 
% mfind 'image.pixels>5M'
or simply get an overview of what kind of files (MIME type) reside on your volume: 
% mfind -H mime:
mime:
           text/html: ################################################################################(8456)    
          image/jpeg: ############(1270)  |         |         |         |         |         |         |         
           image/gif: #(139)    |         |         |         |         |         |         |         |         
          text/plain: #(69)     |         |         |         |         |         |         |         |         
         image/x-png: (40)      |         |         |         |         |         |         |         |         
ication/octet-stream: (20)      |         |         |         |         |         |         |         |         
     application/pdf: (5)       |         |         |         |         |         |         |         |         
           audio/mp3: (5)       |         |         |         |         |         |         |         |         
     application/zip: (4)       |         |         |         |         |         |         |         |         
  application/x-marc: (1)       |         |         |         |         |         |         |         |         
     application/ogg: (1)       |         |         |         |         |         |         |         |         
  application/msword: (1)       |         |         |         |         |         |         |         |         
          audio/mpeg: (1)       |         |         |         |         |         |         |         |         
          video/webm: (1)       |         |         |         |         |         |         |         |         
                      |0.0      |1057.0   |2114.0   |3171.0   |4228.0   |5285.0   |6342.0   |7399.0   |8456.0

Due the richness of metadata extraction from common file formats, you can search and find and sort accordingly as you can see - this is an extremely powerful feature.

4. Adding Metadata

Further, you can manually add custom metadata as you like: 
% mmeta --rating=10 AA.txt
      rating: 10

% mls -l AA.txt
AA.txt
       uid: c8b93ea21191343b49b8816d18a7f34f47c47aeb38e3512bf64cd9784f566f6b
      size: 15 bytes
      mime: text/plain
     utime: 2013/12/15 14:14:27.350 (1day 4hrs 15mins 13secs ago)
     mtime: 2013/12/15 14:14:27.350 (1day 4hrs 15mins 13secs ago)
     ctime: 2013/12/15 14:14:27.333 (1day 4hrs 15mins 14secs ago)
     atime: 2013/12/15 14:14:27.350 (1day 4hrs 15mins 13secs ago)
      hash: 1341566a646b4e759d3cf63e8e59be9c52d47d55701d7f941334b58030460eb6
    rating: 10
      text:
      excerpt: this is a text
   version: 1

% mfind 'rating>5'
rating:
   AA.txt
        rating: 10
   timings.txt
        rating: 7

or add a GPS location to an item, e.g. a photo like DSC_00100.jpg has no GPS information whatsoever:

  1. we assign manually a city (and country if necessary if there is ambiguity)
  2. automatically lookup GPS coordinates, and use them as well (built-in Geonames permits this) 
% mmeta -l --location.city=Denver DSC_00100.jpg
      location.city: Denver
      location.country: US
      location.lat: 39.7384972222222
      location.long: -104.987052777778
      location.elevation: 1576

DSC_00100.jpg
       uid: 6fda66ab7c0d7eb5a032a2b9fb03ca9e5ba525bd3746a0e9afcbabf82eaafe22
      size: 677,576 bytes
      mime: image/jpeg
     utime: 2013/12/16 11:44:43.418 (2hrs 4mins 23secs ago)
     mtime: 2005/09/11 21:37:14.000 (8years 3months 17days 17hrs 11mins 52secs ago)
     ctime: 2013/12/16 11:44:43.168 (2hrs 4mins 23secs ago)
     atime: 2013/12/16 11:44:43.418 (2hrs 4mins 23secs ago)
      hash: c0464fa84ec6b8dbb9d7271c2c27541a056e3a9d40bc81120eaf04d6643e175a
     image:
         EXIF:
        Aperture: 5.5
         ...
       height: 1536 px
       vector: 616c91777d9ec1c8d584838c7d7d8eb1b5c065666a5053618d8f92
        width: 2048 px
  location:
         city: Denver
         country: US
         elevation: 1576
         lat: 39.7384972222222
         long: -104.987052777778
         ...
   version: 1

of course you can assign the latitude/longitude GPS coordinates direct: 

% mmeta --location.lat=39.7 --location.long=-104.9 DSC_00100.jpg
location.lat: 39.7
location.long: -104.9
once the GPS location is set, we can query for it by simply mentioning a city (-v added so query shows some details): 
% mfind -v location:Denver
searching term 'location:Denver'
lookup 'Denver' () -> lat=39.73915,long=-104.9847
search at lat=39.73915,long=-104.9847 with dist 10,000m
location:
   DSC_00100.jpg
     location: {
         dist: 8,461.21808343057 m
         lat: 39.7
         long: -104.9
     }
The location.dist is only calculated & displayed based on the lat/long search point for this lookup (not stored in the metadata). Of course you can change the default distance it should look, from 10km to whatever.


These are the basics of MetaFS. For the impatient, check Quick Reference, and for more in-depth information consult the comprehensive MetaFS Handbook and MetaFS Cookbook.