diff --git a/docs/system_overview/genquery.md b/docs/system_overview/genquery.md index e7f343d..34bc395 100644 --- a/docs/system_overview/genquery.md +++ b/docs/system_overview/genquery.md @@ -201,6 +201,18 @@ There are a few other options that can be used with GenQuery to affect how the r - no-distinct: Instructs GenQuery to return all results, even repeating identical results where applicable. - uppercase: When specified, all VALUEs should be supplied in UPPERCASE and the query will be made case-insensitive. +### Collation Order + +It should be noted, with regard to the case-sensitive query defaults, that one cannot always rely on an assumed collation order (i.e. the result of comparing mixed-case string arguments) to be followed. That is because a particular de facto ordering within a character set - as implied by GenQuery operators such as <, =, >, BETWEEN, and ORDER (BY) - can easily be impacted by the configuration and design of the backing DBRMS which implements those operators. + +Consider the following query for example, when run in the context of three data objects named `a`, `A`, and `a_`: + +```sql +select DATA_NAME where DATA_NAME between 'a' 'a_' +``` + +Under the default American setup of MySQL, for example, 'A' will fall in the range defined by `between` (as corroborated by testing the result of the query `select 'a' <= 'A' and 'A' <= 'a_'` in the mysql client) and thus be reported among GenQuery's results; whereas under the default setup of PostgreSQL, it will not. + ### Attributes GenQuery attributes can be used in concert to retrieve information about an entity or category of entities from multiple different tables. If the attributes are not related in some way that will allow for table joinery, an error will occur, so make sure the query makes logical sense. Attempting a query where the selected ATTRIBUTEs cannot be logically linked together will result in the error `CAT_FAILED_TO_LINK_TABLES` (iRODS error code -825000). If this problem occurs, consider splitting the query into multiple queries or finding another ATTRIBUTE which will accomplish the task.