Help:Type Record

From semantic-mediawiki.org
Jump to: navigation, search
Record
Allows saving compound property values that consist of a short list of values with fixed type and order
Further Information
Provided by: Semantic MediaWiki
Added in version: 1.6.0
Removed in version: still in use
Table of Contents

The datatype record is used for property values that consist of a short list of values of other datatypes. For each property that uses this datatype, the order and type of the individual fields of the record is fixed, based on a Has fields declaration on the property page. Individual fields in a record value are separated with semicolons (;).

In earlier versions of SMW, record properties have also been called many-valued properties or n-ary properties.

Declaration and usage

A record property is declared by writing [[Has type::Record]] on the respective property page, and by setting the properties of the record's fields with the special property Has fields. For example you would define a property of datatype record like this:

[[Has fields::"name of my property of type page"; "name of my property of type number"; "name of my property of type string"]]

Hence the single fields refer to properties and not to datatypes as in versions of SMW prior to 1.6.0. The use of properties instead of datatypes is better since it allows custom settings beyond the datatype of a field (e.g. conversion factors). In case your are upgrading your wiki containing properties of type record from a version of SMW prior to 1.6.0 to 1.6.0 or above see the instructions on this help page for steps on how to do this.

In a similar way as explained above, you can set any list of properties for the record. It is recommended that the number of fields in a record does not exceed five, but larger records are possible. There are some technical restrictions on record sizes, so record declarations with more than 50 fields are likely to fail. Note that records are already unusable for human editors at much shorter lengths.

When using a record-type property on a page, the values for the individual fields are given as a value, separated by semicolons. If the property "Myrecord" were declared as above, one could write the following annotation on a page:

[[Myrecord::Some pagename; 1234; some string]]

When setting a value for a record-type property, it is also possible to leave some of the fields unset by leaving them empty or setting question marks:

[[Myrecord::Some pagename; ?; some string]]
[[Myrecord::Some pagename;; some string]]

Values at the end of the record can also be omitted completely:

[[Myrecord::Some pagename; 1234]]

Example

For a typical example for using records, assume that you want to store information about the presidents of the U.S.A. in a wiki page about that country. You could simply write [[Has president::John F. Kennedy]] to state that Kennedy is among the presidents, but this would not allow you to see when Kennedy was president, and it would be impossible to find out the current president.

The fact that Kennedy was the 35th president of the U.S.A., serving from 1961 until his assassination in 1963, consists of various pieces of information that belong together. Setting independent property values [[Has president::John F. Kennedy]], [[In office since::1961]], [[In office until::1963]] would not solve the problem if the page contains many presidents, since one could no longer know which in-office dates belong to which president.

A possible solution is to declare the property "Has president" to be a record with fields [[Has fields::Has name; In office since; In office until]]. Here the property "Has name" would be of type Page or String, the properties "In office since" and "In office until" would be of type Date. One could then write a fact as [[Has president::John F. Kennedy; 1961; 1963]] so as to group these pieces of information. As explained above, one could also omit some of the fields if they are unknown or non-applicable, e.g. when writing [[Has president::Barack Obama; 2009]] where the end of office is not known yet.

Another possible solution to this modelling problem is to create one article for each presidency, and to assign individual fields values to this article instead. For example, one could have a page Kennedy's presidency that is annotated with individual property values for person, start and end of office. Thus it would be possible to insert the information about the presidents to a page about the U.S.A via an inline query.

Semantic search

Using record properties for searching pages can be done in a similar fashion as for all other properties; see Help:Semantic search. As with any property, you can use the + wildcard to select all pages with some value for a record property, for example {{#ask: [[Employment::+]] }}. To find pages that match a particular value for some of the fields of the record, just list the values to match, separated by semicolons. If you do not care about the value of one of the datatypes, use ? to match any value for it including omitted.

The values given for fields in a record query are written according to the datatype of the field. For most datatypes, this means that comparators such as ! for not, < for less than or equal to can be used with each field.

For example,
{{#ask: [[Employment:: ?; !professorship; <July 1950; ?]] }}
selects values for the property Employment with any value for the employer string, where the title string is not "professorship", the start date is before July 1951, and with any value for end date.

When displaying the values of records in query results, it is possible to use the printout parameter index to obtain a particular field of the record. For example, one can write the following query:

{{#ask: [[U.S.A.]]
| ?has president
| ?has president#name  |+index=1
| ?has president#start |+index=2
| ?has president#end   |+index=3
}}

to display all presidents of the U.S.A. in a table: the first column shows the complete record, the second shows only the first field (name), and the third and fourth show that second and third field, respectively (start and end of office).

Note that the only "result" of this query is the page U.S.A so the table has a single row that shows all of this page's values for has president, not many rows for each president. The latter cannot be achieved with records.

Note also that this might result in some unintuitive query results. While SMW query constraints are applied to select matching Wiki pages:

 {{#ask: [[Employment:: ?; !professorship; <July 1950; ?]] }}

the final result set will contain all employments of these matching Wiki pages - even those which do not satisfy the query constraints - due to the way SMW deals with records in queries (i.e., query constraints are used to match pages, and in a second steps, all values of the property under consideration are returned - irrespective of if they satisfy query constraints).

Limitations

  • You cannot use the special Display units property to control how a specific field appears.
  • You cannot set the layout of the values; they will always appear as a comma-separated list.
  • Fields of records cannot be the basis for special purpose query formats such as Timeline or geography related ones, etc.

Alternatives

If you have a one to many relationship, then one of the two alternatives is going to be more appropriate, because you can query for them on one property, and retrieve the other properties (example below). Think of them as pages without having to have their own page (cluttering up your wiki).

However, if you have a one to one (page to property value) relationship (enforced by form and template), then you could use either, but a record is going to be easier.

parser function #subobject

See the help page Adding subobjects for a detailed description of this built-in alternative, which is available since SMW 1.7.0.

parser function #set_internal

This alternative is provided by the Semantic Internal Objects extension to SMW.

Example "Semantic City"

It has several museums:

  • {{museum|Museum of Modern Art|1000|1800}}
  • {{museum|Museum of Natural History|0930|1730}}

Where your museum template would set an internal object

 {{#set_internal:is museum in city
 |has name={{{1}}}
 |has opening time={{{2|}}}
 |has closing time={{{3|}}}
 }}
and display something too.

Now you can query for museums in a given city, and display their opening times.

 {{#ask: [[is museum in city::Semantic City]] [[has name::~*History*]]
 |?has name=Museum
 |?has opening time=opens
 |?has closing time=closes
 |mainlabel=-
 }}



This documentation page applies to all SMW versions from 1.6.0 to the most current version.
Other versions: 1.5.0 – 1.6.0      

Help:Type Record en 1.6.0