User questions

What is FreeTable?

FreeTable is a cross between a traditional Wiki and a database. It provides notions of contributions by multiple users, versioning, and the ability to roll changes forwards and back, much like a Wiki, while the data itself is stored in a tabular format familiar to anyone who has used a database or spreadsheet.

When might I use FreeTable?

FreeTable can be used most places a database might be used and is especially useful if you wish to share data with others on the Internet.

How do I upload data to FreeTable?

You can either upload tables by creating an account, logging in, and using the csv upload facility on the account page, or if you are a developer you can use the FreeeTable query language to connect to the FreeTable database directly.

What is the maximum supported table size?

1 GB of space actually consumed. Space is required for memory storage values, hidden columns, and indexes, so the amount of original JSON data actually stored may be 500 MB or less. This would be sufficient for 500,000 rows, each 1 kB in size.

Rows are limited to 1MB of JSON data storage.

Consideration can be given to increasing either of these limits on a per table basis. We should readily be able to handle rows of up to 100MB and tables of up to 10GB. With a little prodding and/or hardware reconfiguration we should be able to handle tables up to about 50GB in size.

Table browser/editor questions

What does curated mean?

A curated table is one in which inserts and updates don't have immediate effect, but are held for the tables's curators to review. A curated table normally requires history be maintained.

What does history mean?

History refers to whether old revisions of data are kept by the system for potential rollback/rollforward.

What does visible mean?

Whether inserts of new/updated data are made visible to users as pending changes via the "select ... all_rows ..." construct, or whether a hard limit preventing access of newly inserted/updated data is imposed.

What are permissions?

Permissions control who may do what to the table. They are explained in the FreeTable Developer Tutorial and FreeTable Developer Specification.

What is the difference between the table license and the required row license?

Copyright law distinguishes between the copyright on individual data elements (possibly none), and on a compilation of data elements such as a data table. The table license or licenses (you may have a choice) define the licensing terms offered to you for the table as a whole. The required row license defines the copyright licensing terms people are required to grant for newly inserted or updated rows they provide in order for them to be incorporated into the table. If they don't agree to grant these rights, they won't be able to insert data in the table.

FreeTable supports several data as a whole table licenses:

  • Public_Domain - the public domain
  • ODC-ODbL-1.0 - an attribution and share-alike license
  • ODC-By-1.0 - an attribution license
  • Other_OKD_Compliant - other licenses compliant with the Open Knowledge Definition
And several single data element row licenses:

FreeTable recommends the ODC-ODbL-1.0 table license and accepting rows under any of the Public_Domain, CC-by-3.0, and CC-by-sa-3.0 licenses.

What is a table curator?

The curators are responsible for management of the table. This includes approving new or updated rows if the table is curated. Curators can be either individual users or groups of users, and the curators of a table are represented in the table browser by a space separated list.

What is a table sponsor?

The sponsor is responsible for the payment of any fees associated with the table. The plan is to charge a fee for large tables that receive a low transactional volume in order to either discourage them or make them share in the heavy cost of their presence in the system.

How do I make a table non-curated?

Using the table browser navigate to the table in question, select "View/edit table information" then "Edit table information". De-select "curated" and change the last two "Permissions" to "--", then hit Update. Setting the permissions is necessary because non-curated tables are not allowed to have anonymous inserts/updates.

Developer questions

Why isn't my table listed in searches of tables from the home page?

You need to turn on the "advertise" bit to indicate you want your table included in the home page search listings: 

    update information_schema.tables set {"advertise": true} where table_name="<my_table_name>"
Without the advertise bit turned on, your table can only be found by specifying its full exact name.

What should I name my table?

If you are experimenting with FreeTable, or you will be the only user of the table, it is recommended that you refer to it as <table>, user.<username>.<table>, or local.<table>. All of these forms are equivalent. If you intend for others to make use of the table it is recommended that you give the table a name in the global namespace, global.<table>, where <table> has been carefully thought out to be both concise and descriptive. As an example, global.iana.tlds, for the top level domain name table produced by IANA, or global.us.cpi, for the US consumer price index. The general principle is to go from the less specific to the more specific. Don't use your username in the title. If you want to do that, and you can if you want, you should use the local name, user.<username>.<table>.

What is the FreeTable table namespace?

  • global.* - Global public name space; general to specific; be prepared for names to be renamed by FreeTable upon careful consideration.
  • user.<username>.* - Per user name space.
  • local.* - A user specific synonym for user.<username>.*
  • information_schema.* - FreeTable internal use.
  • dns.* - Reserved for possible DNS ontology.
The default namespace for a table name without any dots is local.

Why don't I see inserts/updates?

The table is probably curated. This is the default for newly created tables. Curation allows the table owner to approve or reject changes by marking records as current and moving them from the "pending" to the "accepted" or "rejected" states.

Curation can be turned off for a table: 

    update information_schema.tables set {"curated": false} where table_name="<my_table_name>"
or individually records can be made current, accepted, or rejected, by logging in to the table browser.

I still don't see inserts/deletes?

Perhaps visible is turned off. However, this should not be the case for a newly created table. Visibility is orthogonal to curation. Curation determines whether a newly inserted/updated record will be marked as current, while visibility provides hard limits on data access that can't be overridden other than by the table owner.

Visibility can be turned on for newly inserted records in a table: 

    update information_schema.tables set {"visible": true} where table_name="<my_table_name>"
What is history?

History is the set of all revisions of a record. By default history is saved so that changes can be rolled back or forward. History can be removed while leaving any current records in place by using the purge command. 

    purge from <my_table_name> where ...

For frequently changing records it may be more appropriate to turn history off: 

    update information_schema.tables set {"history": false} where table_name="<my_table_name>"
Update hidden is broken.

Update hidden is typically used to make non-current rows of a table that utilizes history current. Non-current rows are row values that have been superseded or held for the curators to review. When using update hidden, it should normally be specified in conjunction with the all_rows modifier, otherwise it will only apply to current rows, which is probably not what is wanted, and will typically have little effect. 

    update hidden_columns <my_table_name> all_rows set _current=true where ...
What is FreeTable's policy on encrypted content?

Generally content on FreeTable needs to be transparent. It should be clear to a third party what the content represents and how to use it. An exception is made for storing passwords and other similar opaque hashed data, but such data should be small, less than a thousand bytes per record.