Help:Datatype "Record"
| This page contains outdated information and is thus OBSOLETE! |
| The revision id is not annotated properly in the master page! The template {{Docinfo}} may not be embedded in: Help:Datatype "Record" |
| 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 |
| Since version: | 1.5.0 |
| Until version: | still in use |
| Datatype ID: | |
| In this wiki: | Record |
| 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 Semantic MediaWiki, record properties have also been called many-valued properties or n-ary properties.
Declaration and usage[edit]
A record property is declared by writing [[has type::record]] on the respective property page, and by setting the types of the record's fields with the property Has fields. For example, to define a record with a Date, a Page and a Number field, you can write
[[has fields::Date; Page; Number]]
In a similar way, you can set any list of types 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::May 12 1005; Some pagename; 1234]]
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::May 12 1005; ?; 1234]] [[myrecord::May 12 1005;; 1234]]
Values at the end of the record can also be omitted completely:
[[myrecord::May 12 1005; Some pagename]]
If the value that is given for some field in the record is not allowed for the datatype declared for this field, Semantic MediaWiki will also try to leave the field empty and use the value for the next field. For example, [[myrecord::Some pagename; 1234]] is interpreted as [[myrecord::?; Some pagename; 1234]]
Example[edit]
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::Page; Date; 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[edit]
Using record properties for searching pages can be done in a similar fashion as for all other properties; see 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[edit]
At least some of the following limitations no longer hold for SMW 1.6 and greater.
- You cannot use the special Allows value property to limit the values of any field of a record.
- 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 Timelines or Maps.
- Records cannot be nested, and thus can only consist of simple datatypes.
Alternatives[edit]
As an alternative to the datatype record, you can also consider using the extension Semantic Internal Objects.
- When to use datatype record and when to use Semantic Internal Objects (SIO)?
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.
If you have a one to many relationship, then SIOs are 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).
Example page "Semantic City"
The mayor is [[has mayor until date::John Smith;2012|John Smith (term ends in 2012)]]
It has several museums: {{museum|Museum of Modern Art|1000|1800}} {{museum|Natural History Museum|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=-
}}
