Properties and Columns

A property is a key-value pair associated with an entry. Properties can be set, so they are associated with a single entry, with every entry in a tree, or with the whole buffer.

There are two main applications for properties in Org mode. First, properties are like tags, but with a value. Imagine maintaining a file where you document bugs and plan releases for a piece of software. Instead of using tags like release_1, release_2, you can use a property, say Release, that in different subtrees has different values, such as 1.0 or 2.0. Second, you can use properties to implement (very basic) database capabilities in an Org buffer. Imagine keeping track of your music CDs, where properties could be things such as the album, artist, date of release, number of tracks, and so on.

Properties can be conveniently edited and viewed in column view (see Column View).

Property Syntax

Properties are key–value pairs. When they are associated with a single entry or with a tree they need to be inserted into a special drawer (see Drawers) with the name PROPERTIES, which has to be located right below a headline, and its planning line (see Deadlines and Scheduling) when applicable. Each property is specified on a single line, with the key—surrounded by colons—first, and the value after it. Keys are case-insensitive. Here is an example:

* CD collection
** Classic
*** Goldberg Variations
    :PROPERTIES:
    :Title:     Goldberg Variations
    :Composer:  J.S. Bach
    :Artist:    Glenn Gould
    :Publisher: Deutsche Grammophon
    :NDisks:    1
    :END:

Depending on the value of org-use-property-inheritance, a property set this way is associated either with a single entry, or with the subtree defined by the entry, see Property Inheritance.

You may define the allowed values for a particular property Xyz by setting a property Xyz_ALL. This special property is inherited, so if you set it in a level 1 entry, it applies to the entire tree. When allowed values are defined, setting the corresponding property becomes easier and is less prone to typing errors. For the example with the CD collection, we can pre-define publishers and the number of disks in a box like this:

* CD collection
  :PROPERTIES:
  :NDisks_ALL:  1 2 3 4
  :Publisher_ALL: "Deutsche Grammophon" Philips EMI
  :END:

Properties can be inserted at the buffer level. That means they apply before the first headline and can be inherited by all entries in a file. Property blocks defined before the first headline must be at the top of the buffer with only comments above them.

Properties can also be defined using lines like:

#+PROPERTY: NDisks_ALL 1 2 3 4

If you want to add to the value of an existing property, append a + to the property name. The following results in the property var having the values foo and bar.

#+PROPERTY: var  foo
#+PROPERTY: var+ bar

Using the appended +, it is also possible to add to the values of inherited properties. The following results in the Genres property having the values Classic, Baroque, and Keyboard music under the Goldberg Variations subtree.

* CD collection
** Classic
    :PROPERTIES:
    :Genres: Classic
    :END:
*** Goldberg Variations
    :PROPERTIES:
    :Title:     Goldberg Variations
    :Composer:  J.S. Bach
    :Artist:    Glenn Gould
    :Publisher: Deutsche Grammophon
    :NDisks:    1
    :Genres+:   Baroque
    :Genres+:   Keyboard music
    :END:

Note that a property can only have multiple entries per drawer when used with the appended +. When a property has multiple entries without +, the result is undefined.

Property values set with the global variable org-global-properties can be inherited by all entries in all Org files.

The following commands help to work with properties:

M-TAB (pcomplete)

After an initial colon in a line, complete property keys. All keys used in the current file are offered as possible completions.

C-c C-x p (org-set-property)

Set a property. This prompts for a property name and a value. If necessary, the property drawer is created as well.

C-u M-x org-insert-drawer

Insert a property drawer into the current entry. The drawer is inserted early in the entry, but after the lines with planning information like deadlines. If before first headline the drawer is inserted at the top of the drawer after any potential comments.

C-c C-c (org-property-action)

With point in a property drawer, this executes property commands.

C-c C-c s (org-set-property)

Set a property in the current entry. Both the property and the value can be inserted using completion.

S-RIGHT (org-property-next-allowed-value), S-LEFT (org-property-previous-allowed-value)

Switch property at point to the next/previous allowed value.

C-c C-c d (org-delete-property)

Remove a property from the current entry.

C-c C-c D (org-delete-property-globally)

Globally remove a property, from all entries in the current file.

C-c C-c c (org-compute-property-at-point)

Compute the property at point, using the operator and scope from the nearest column format definition.

Special Properties

Special properties provide an alternative access method to Org mode features, like the TODO state or the priority of an entry, discussed in the previous chapters. This interface exists so that you can include these states in a column view (see Column View), or to use them in queries. The following property names are special and should not be used as keys in the properties drawer:

`ALLTAGS`	All tags, including inherited ones.
`BLOCKED`	`t` if task is currently blocked by children or siblings.
`CATEGORY`	The category of an entry.
`CLOCKSUM`	The sum of CLOCK intervals in the subtree. `org-clock-sum`
	must be run first to compute the values in the current buffer.
`CLOCKSUM_T`	The sum of CLOCK intervals in the subtree for today.
	`org-clock-sum-today` must be run first to compute the
	values in the current buffer.
`CLOSED`	When was this entry closed?
`DEADLINE`	The deadline timestamp.
`FILE`	The filename the entry is located in.
`ITEM`	The headline of the entry.
`PRIORITY`	The priority of the entry, a string with a single letter.
`SCHEDULED`	The scheduling timestamp.
`TAGS`	The tags defined directly in the headline.

`TIMESTAMP`	The first active keyword-less timestamp in the entry.¹⁷
`TIMESTAMP_IA`	The first inactive keyword-less timestamp in the entry.
`TODO`	The TODO keyword of the entry.

Property Searches

To create sparse trees and special lists with selection based on properties, the same commands are used as for tag searches (see Tag Searches).

C-c / m or C-c \ (org-match-sparse-tree)

Create a sparse tree with all matching entries. With a C-u prefix argument, ignore headlines that are not a TODO line.

M-x org-agenda m (org-tags-view)

Create a global list of tag/property matches from all agenda files.

M-x org-agenda M (org-tags-view)

Create a global list of tag matches from all agenda files, but check only TODO items.

The syntax for the search string is described in Matching tags and properties.

There is also a special command for creating sparse trees based on a single property:

C-c / p

Create a sparse tree based on the value of a property. This first prompts for the name of a property, and then for a value. A sparse tree is created with all entries that define this property with the given value. If you enclose the value in curly braces, it is interpreted as a regular expression and matched against the property values (see Regular Expressions).

Property Inheritance

The outline structure of Org documents lends itself to an inheritance model of properties: if the parent in a tree has a certain property, the children can inherit this property. Org mode does not turn this on by default, because it can slow down property searches significantly and is often not needed. However, if you find inheritance useful, you can turn it on by setting the variable org-use-property-inheritance. It may be set to t to make all properties inherited from the parent, to a list of properties that should be inherited, or to a regular expression that matches inherited properties. If a property has the value nil, this is interpreted as an explicit un-define of the property, so that inheritance search stops at this value and returns nil.

Org mode has a few properties for which inheritance is hard-coded, at least for the special applications for which they are used:

COLUMNS

The COLUMNS property defines the format of column view (see Column View). It is inherited in the sense that the level where a COLUMNS property is defined is used as the starting point for a column view table, independently of the location in the subtree from where columns view is turned on.

CATEGORY

For agenda view, a category set through a CATEGORY property applies to the entire subtree.

ARCHIVE

For archiving, the ARCHIVE property may define the archive location for the entire subtree (see Moving a tree to an archive file).

LOGGING

The LOGGING property may define logging settings for an entry or a subtree (see Tracking TODO state changes).

Column View

A great way to view and edit properties in an outline tree is column view. In column view, each heading is turned into a table row. Columns in this table provide access to properties of the entries. Org mode implements columns by overlaying a tabular structure over the headline of each item. While the headlines have been turned into a table row, you can still change the visibility of the outline tree. For example, you get a compact table by switching to "contents" view—S-TAB S-TAB, or simply c while column view is active—but you can still open, read, and edit the entry below each headline. Or, you can switch to column view after executing a sparse tree command and in this way get a table only for the selected items. Column view also works in agenda buffers (see Agenda Views) where queries have collected selected items, possibly from a number of files.

Defining columns

Setting up a column view first requires defining the columns. This is done by defining a column format line.

Scope of column definitions

To specify a format that only applies to a specific tree, add a COLUMNS property to the top node of that tree, for example:

** Top node for columns view
   :PROPERTIES:
   :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
   :END:

A COLUMNS property within a property drawer before first headline will apply to the entire file. As an addition to property drawers, keywords can also be defined for an entire file using a line like:

#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO

If a COLUMNS property is present in an entry, it defines columns for the entry itself, and for the entire subtree below it. Since the column definition is part of the hierarchical structure of the document, you can define columns on level 1 that are general enough for all sublevels, and more specific columns further down, when you edit a deeper part of the tree.

Column attributes

A column definition sets the attributes of a column. The general definition looks like this:

%[WIDTH]PROPERTY[(TITLE)][{SUMMARY-TYPE}]

Except for the percent sign and the property name, all items are optional. The individual parts have the following meaning:

WIDTH

An integer specifying the width of the column in characters. If omitted, the width is determined automatically.

PROPERTY

The property that should be edited in this column. Special properties representing metadata are allowed here as well (see Special Properties).

TITLE

The header text for the column. If omitted, the property name is used.

SUMMARY-TYPE

The summary type. If specified, the column values for parent headings are computed from the direct children. If there is any existing property defined for the parent nodes, it is not used in the calculations.

When there is an existing property in parent heading, Org does not only overlay the computed value in the column view, but also overwrites the property value in parent's property drawer(note: If more than column definition is requested for the same property, only the first definition will trigger writing to the property drawer. For example, %EFFORT{mean} %EFFORT(Sum){:} will write the mean value of EFFORT property; not the sum. If the first column definition does not have summary type (%EFFORT %EFFORT{mean}), nothing will be written to the property drawer).

Summary type is ignored for special properties.

Supported summary types are:

`+`	Sum numbers in this column.
`+;%.1f`	Like `+`, but format result with `%.1f`.
`$`	Currency, short for `+;%.2f`.
`min`	Smallest number in column.
`max`	Largest number.
`mean`	Arithmetic mean of numbers.
`X`	Checkbox status, `[X]` if all children are `[X]`.
`X/`	Checkbox status, `[n/m]`.
`X%`	Checkbox status, `[n%]`.
`:`	Sum times, HH:MM, plain numbers are minutes.
`:min`	Smallest time value in column.
`:max`	Largest time value.
`:mean`	Arithmetic mean of time values.

`@min`	Minimum age¹⁸ (in days/hours/mins/seconds).
`@max`	Maximum age (in days/hours/mins/seconds).
`@mean`	Arithmetic mean of ages (in days/hours/mins/seconds).
`est+`	Add low-high estimates.

You can also define custom summary types by setting org-columns-summary-types.

The est+ summary type requires further explanation. It is used for combining estimates, expressed as low-high ranges. For example, instead of estimating a particular task will take 5 days, you might estimate it as 5–6 days if you're fairly confident you know how much work is required, or 1–10 days if you do not really know what needs to be done. Both ranges average at 5.5 days, but the first represents a more predictable delivery.

When combining a set of such estimates, simply adding the lows and highs produces an unrealistically wide result. Instead, est+ adds the statistical mean and variance of the subtasks, generating a final estimate from the sum. For example, suppose you had ten tasks, each of which was estimated at 0.5 to 2 days of work. Straight addition produces an estimate of 5 to 20 days, representing what to expect if everything goes either extremely well or extremely poorly. In contrast, est+ estimates the full job more realistically, at 10–15 days.

Here is an example for a complete columns definition, along with allowed values(note: Please note that the COLUMNS definition must be on a single line; it is wrapped here only because of formatting constraints.).

:COLUMNS:  %25ITEM %9Approved(Approved?){X} %Owner %11Status \
                   %10Time_Estimate{:}
:Owner_ALL:    Tammy Mark Karl Lisa Don
:Status_ALL:   "In progress" "Not started yet" "Finished" ""
:Approved_ALL: "[ ]" "[X]"

The first column, %25ITEM, means the first 25 characters of the item itself, i.e., of the headline. You probably always should start the column definition with the ITEM specifier. The other specifiers create columns Owner with a list of names as allowed values, for Status with four different possible values, and for a checkbox field Approved. When no width is given after the % character, the column is exactly as wide as it needs to be in order to fully display all values. The Approved column does have a modified title (Approved?, with a question mark). Summaries are created for the Time_Estimate column by adding time duration expressions like HH:MM, and for the Approved column, by providing an [X] status if all children have been checked.

The CLOCKSUM and CLOCKSUM_T column properties are special, they list the sums of CLOCK: intervals in the subtree, either for all clocks (CLOCKSUM) or just for today (CLOCKSUM_T). Unlike : summary type that ignores property values in parent headings, all the CLOCK: intervals are summed up, including CLOCK: lines within parent headings.

Summaries in deeply nested hierarchy

When computing summaries of deeply nested headings, the summaries are computed recursively, from the deepest level to the shallowest. Here is an example:

#+BEGIN: columnview :indent t :format "%ITEM %EFFORT{:mean}" :id global
| ITEM               | EFFORT  |
|--------------------+---------|
| Top level          | 3h 0min |
| \_  Intermediate 1 | 1h 0min |
| \_        Leaf 1   | 1h      |
| \_    Leaf 2       | 1h      |
| \_    Leaf 3       | 1h      |
| \_  Intermediate 2 | 5h      |
#+END:

* Top level
** Intermediate 1
:PROPERTIES:
:EFFORT:   *unused*, will be set to 1h 0min (mean of the leaf nodes)
:END:
***** Leaf 1
:PROPERTIES:
:EFFORT: 1h
:END:
*** Leaf 2
:PROPERTIES:
:EFFORT: 1h
:END:
*** Leaf 3
:PROPERTIES:
:EFFORT: 1h
:END:
** Intermediate 2
:PROPERTIES:
:EFFORT: 5h
:END:

Using column view

Turning column view on or off

C-c C-x C-c (org-columns)

Turn on column view. If point is before the first headline in the file, column view is turned on for the entire file, using the #+COLUMNS definition. If point is somewhere inside the outline, this command searches the hierarchy, up from point, for a COLUMNS property that defines a format. When one is found, the column view table is established for the tree starting at the entry that contains the COLUMNS property. If no such property is found, the format is taken from the #+COLUMNS line or from the variable org-columns-default-format, and column view is established for the current entry and its subtree.

r or g on a columns view line (org-columns-redo)

Recreate the column view, to include recent changes made in the buffer.

C-c C-c or q on a columns view line (org-columns-quit)

Exit column view.

Editing values

LEFT, RIGHT, UP, DOWN: Move through the column view from field to field.
1..9\,0

Directly select the Nth allowed value, 0 selects the 10th value.

n or S-RIGHT (org-columns-next-allowed-value) and p or S-LEFT (org-columns-previous-allowed-value)

Switch to the next/previous allowed value of the field. For this, you have to have specified allowed values for a property.

e (org-columns-edit-value)

Edit the property at point. For the special properties, this invokes the same interface that you normally use to change that property. For example, the tag completion or fast selection interface pops up when editing a TAGS property.

C-c C-c (org-columns-toggle-or-columns-quit)

When there is a checkbox at point, toggle it. Else exit column view.

v (org-columns-show-value)

View the full value of this property. This is useful if the width of the column is smaller than that of the value.

a (org-columns-edit-allowed)

Edit the list of allowed values for this property. If the list is found in the hierarchy, the modified values are stored there. If no list is found, the new value is stored in the first entry that is part of the current column view.

Modifying column view on-the-fly

< (org-columns-narrow) and > (org-columns-widen)

Make the column narrower/wider by one character.

S-M-RIGHT (org-columns-new)

Insert a new column, to the left of the current column.

S-M-LEFT (org-columns-delete)

Delete the current column.

M-LEFT (org-columns-move-left)

Move the current column left.

M-RIGHT (org-columns-move-right)

Move the current column right.

M-UP (org-columns-move-row-up)

Move the current row up.

M-DOWN (org-columns-move-row-down)

Move the current row down.

Capturing column view

Since column view is just an overlay over a buffer, it cannot be exported or printed directly. If you want to capture a column view, use a columnview dynamic block (see Dynamic Blocks). The frame of this block looks like this:

* The column view
#+BEGIN: columnview :hlines 1 :id "label"

#+END:

This dynamic block has the following parameters:

:id

This is the most important parameter. Column view is a feature that is often localized to a certain (sub)tree, and the capture block might be at a different location in the file. To identify the tree whose view to capture, you can use four values:

local: Use the tree in which the capture block is located.
global: Make a global view, including all headings in the file.
file:FILENAME: Run column view at the top of the FILENAME file.
LABEL

Call column view in the tree that has an ID property with the value LABEL. You can use M-x org-id-copy to create a globally unique ID for the current entry and copy it to the kill-ring.

:match: When set to a string, use this as a tags/property match filter to select only a subset of the headlines in the scope set by the :id parameter.

:hlines: When t, insert an hline after every line. When a number N, insert an hline before each headline with level <= N.
:vlines: When non-nil, force column groups to get vertical lines.
:maxlevel: When set to a number, do not capture entries below this level.
:skip-empty-rows: When non-nil, skip rows where the only non-empty specifier of the column view is ITEM.
:exclude-tags: List of tags to exclude from column view table: entries with these tags will be excluded from the column view.
:indent: When non-nil, indent each ITEM field according to its level.
:link: When non-nil, link the ITEM headlines in the table to their origins.
:format: Specify a column attribute (see Column attributes) for the dynamic block.
:formatter

A function to format column view data and insert it into the buffer. See the option org-columns-dblock-formatter.

The following commands insert or update the dynamic block:

org-columns-insert-dblock

Insert a dynamic block capturing a column view. Prompt for the scope or ID of the view.

This command can be invoked by calling org-dynamic-block-insert-dblock (C-c C-x x) and selecting "columnview" (see Dynamic Blocks).

C-c C-c C-c C-x C-u (org-dblock-update)

Update dynamic block at point. Point needs to be on the #+BEGIN line of the dynamic block.

C-u C-c C-x C-u (org-update-all-dblocks)

Update all dynamic blocks (see Dynamic Blocks). This is useful if you have several clock table blocks, column-capturing blocks or other dynamic blocks in a buffer.

You can add formulas to the column view table, and you may add plotting instructions in front of the table—these survive an update of the block. If there is a TBLFM keyword after the table, the table is recalculated automatically after an update.

An alternative way to capture and process property values into a table is provided by Eric Schulte's org-collector.el, which is a package in =org-contrib=(note: Contributed packages are not part of Emacs, but are distributed with the main distribution of Org—visit https://orgmode.org.). It provides a general API to collect properties from entries in a certain scope, and arbitrary Lisp expressions to process these values before inserting them into a table or a dynamic block.

Footnotes

17
For both TIMESTAMP and TIMESTAMP_IA: the word "first" refers to the first occurrence in the entry, not the earliest in time; the prefix CLOCK: at the beginning of a clock entry is considered a keyword in this context; and timestamps inside property drawers are ignored.

Backrefs: 1
18
An age can be defined as a duration, using units defined in org-duration-units, e.g., 3d 1h. If any value in the column is as such, the summary is also expressed as a duration.

Backrefs: 1