pulldata() was introduced to Collect on top of functionality that loads a CSV into a database.
pulldata() queries that database to pull out a single value. There's more about it in the thread on the state of external data.
The original spec for
pulldata() and the underlying database feature states that any CSV included with a form would be parsed and available for querying based on the original csv's filename. This is not in the spirit of the ODK XForms spec because the form has no explicit knowledge of the external data file. Some years back, @martijnr and @Ukang_a_Dickson made changes to
pyxform such that if the XLSForm uses
pulldata, the corresponding XForm explicitly declares the existence of the CSV file queried by
pulldata. This opens the door for
pulldata to simply be a convenience custom XPath function that hides some of the complexity of XPath queries (much like
pulldata() is already in broad usage and can be implemented consistently across spec-compliant clients, I'd like to propose that it become an official part of the specification. That would help make sure it's thoroughly documented which it isn't right now.
If the form describes an external CSV instance:
<instance id=<instance name> src="jr://file-csv/<filename>" />
The CSV can be queried thus:
pulldata(<instance name>, <return column>, <query column>, <query value>)
<instance id="foo" src="jr://file-csv/my-cool-data.csv" />
pulldata("foo", "Age", "Name", "Bruce Wayne")
This implies that the
my-cool-data.csv file has "Age" and "Name" columns. The function call would return the "Age" value of the row with "Name" "Bruce Wayne."
The example above includes one deviation from current usage in Collect: currently, the instance name must match the filename. That is, for
my-cool-data.csv, the instance ID needs to be
my-cool-data (or to be more precise, the first parameter actually represents the CSV filename). That restriction doesn't make sense in the ODK XForms world so I suggest we do without it. In practice,
pyxform would always make them match.