From 27e757bc44ba12367a4c7dd4143dc3dc7e857d09 Mon Sep 17 00:00:00 2001
From: Dean Rasheed <dar17@cam.ac.uk>
Date: Wed, 22 May 2019 07:53:55 +0000
Subject: [PATCH] Documentation updated to mention how the new Lookup Query
Language (LQL) can be used through the API.
--
Imported using git-svn from
https://dev.csi.cam.ac.uk/svn/lookup/trunk@103
---
src/application.wadl | 80 ++++++++++++++---
src/generate-client-methods.py | 11 ++-
.../ac/cam/ucs/ibis/methods/GroupMethods.java | 23 ++++-
.../ucs/ibis/methods/InstitutionMethods.java | 28 ++++--
.../cam/ucs/ibis/methods/PersonMethods.java | 29 +++++--
src/php/ibisclient/methods/GroupMethods.php | 23 ++++-
.../ibisclient/methods/InstitutionMethods.php | 28 ++++--
src/php/ibisclient/methods/PersonMethods.php | 29 +++++--
src/python/ibisclient/methods.py | 86 ++++++++++++++++---
src/python3/ibisclient/methods.py | 86 ++++++++++++++++---
10 files changed, 349 insertions(+), 74 deletions(-)
diff --git a/src/application.wadl b/src/application.wadl
index f3545eb..004c2a6 100644
--- a/src/application.wadl
+++ b/src/application.wadl
@@ -162,11 +162,19 @@
* By default, only a few basic details about each group are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
+ * <p>
+ * NOTE: If the query string starts with the prefix {@code "group:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> parameter, but it will respect the value of
+ * <code>includeCancelled</code>. In addition, an LQL query will ignore
+ * the <code>orderBy</code> parameter, since LQL queries always return
+ * results in ID order.
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled groups to
* be included. Defaults to {@code false}.
* @param offset [optional] The number of results to skip at the start
@@ -174,8 +182,9 @@
* @param limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param orderBy [optional] The order in which to list the results.
- * This may be {@code "groupid"}, {@code "name"} (the default) or
- * {@code "title"}.
+ * This may be {@code "groupid"}, {@code "name"} (the default for non-LQL
+ * queries) or {@code "title"}. This is ignored for LQL queries, which
+ * always return results in groupid order.
* @param fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -204,11 +213,17 @@
/**
* Count the number of groups that would be returned by a search using
* a free text query string.
+ * <p>
+ * NOTE: If the query string starts with the prefix {@code "group:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> parameter, but it will respect the value of
+ * <code>includeCancelled</code>.
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled groups to
* be included. Defaults to {@code false}.
*
@@ -580,22 +595,33 @@
* By default, only a few basic details about each institution are
* returned, but the optional <code>fetch</code> parameter may be used
* to fetch additional attributes or references.
+ * <p>
+ * NOTE: If the query string starts with the prefix {@code "inst:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> and <code>attributes</code> parameters, but
+ * it will respect the value of <code>includeCancelled</code>. In
+ * addition, an LQL query will ignore the <code>orderBy</code> parameter,
+ * since LQL queries always return results in ID order.
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled institutions
* to be included. Defaults to {@code false}.
* @param attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is {@code null} (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
* @param offset [optional] The number of results to skip at the start
* of the search. Defaults to 0.
* @param limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param orderBy [optional] The order in which to list the results.
- * This may be either {@code "instid"} or {@code "name"} (the default).
+ * This may be either {@code "instid"} or {@code "name"} (the default for
+ * non-LQL queries). This is ignored for LQL queries, which always return
+ * results in instid order.
* @param fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -625,16 +651,23 @@
/**
* Count the number of institutions that would be returned by a search
* using a free text query string.
+ * <p>
+ * NOTE: If the query string starts with the prefix {@code "inst:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> and <code>attributes</code> parameters, but
+ * it will respect the value of <code>includeCancelled</code>.
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled institutions
* to be included. Defaults to {@code false}.
* @param attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is {@code null} (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
*
* @return The number of matching institutions.
*/</doc>
@@ -1167,11 +1200,20 @@
* By default, only a few basic details about each person are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
+ * <p>
+ * NOTE: If the query string starts with the prefix {@code "person:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> and <code>attributes</code> parameters, but
+ * it will respect the values of <code>includeCancelled</code> and
+ * <code>misStatus</code>. In addition, an LQL query will ignore the
+ * <code>orderBy</code> parameter, since LQL queries always return
+ * results in ID order.
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled people to
* be included (people who are no longer members of the University).
* Defaults to {@code false}.
@@ -1189,14 +1231,16 @@
* mutually exclusive.
* @param attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is {@code null} (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
* @param offset [optional] The number of results to skip at the start
* of the search. Defaults to 0.
* @param limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param orderBy [optional] The order in which to list the results.
* This may be either {@code "identifier"} or {@code "surname"} (the
- * default).
+ * default for non-LQL queries). This is ignored for LQL queries, which
+ * always return results in identifier order.
* @param fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -1227,11 +1271,18 @@
/**
* Count the number of people that would be returned by a search using
* a free text query string.
+ * <p>
+ * NOTE: If the query string starts with the prefix {@code "person:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> and <code>attributes</code> parameters, but
+ * it will respect the values of <code>includeCancelled</code> and
+ * <code>misStatus</code>.
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled people to
* be included (people who are no longer members of the University).
* Defaults to {@code false}.
@@ -1249,7 +1300,8 @@
* mutually exclusive.
* @param attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is {@code null} (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
*
* @return The number of matching people.
*/</doc>
diff --git a/src/generate-client-methods.py b/src/generate-client-methods.py
index 9f6b511..cf6df94 100755
--- a/src/generate-client-methods.py
+++ b/src/generate-client-methods.py
@@ -714,8 +714,11 @@ def javadocs_to_pydocs(docs, cls, line_prefix="", method=None):
# Replace <li> with plain text "*" bullet points (reST format)
docs = list_items_to_text(docs)
- # Remove any other HTML tags
- docs = re.sub("<[^>]+>", "", docs)
+ # Remove any other HTML tags, except for <a> tags (links)
+ docs = re.sub("<(?!a|/a)[^>]+>", "", docs)
+
+ # Replace <a href="url">text</a> links with `text <url>`_ reST links
+ docs = re.sub("(?s)<a href=\"([^\"]*)\"[^>]*>([^<]*)</a>", "`\\2 <\\1>`_", docs)
# == End of HTML tag processing ==
@@ -1032,8 +1035,8 @@ def javadocs_to_phpdocs(docs, line_prefix=""):
# Replace <li> with plain text "*" bullet points (reST format)
docs = list_items_to_text(docs)
- # Remove any other HTML tags, except for <code> and <pre> blocks
- docs = re.sub("<(?!code|/code|pre|/pre)[^>]+>", "", docs)
+ # Remove any other HTML tags, except for <a>, <code> and <pre> blocks
+ docs = re.sub("<(?!a|/a|code|/code|pre|/pre)[^>]+>", "", docs)
# == End of HTML tag processing ==
diff --git a/src/java/uk/ac/cam/ucs/ibis/methods/GroupMethods.java b/src/java/uk/ac/cam/ucs/ibis/methods/GroupMethods.java
index df0d2be..726e282 100644
--- a/src/java/uk/ac/cam/ucs/ibis/methods/GroupMethods.java
+++ b/src/java/uk/ac/cam/ucs/ibis/methods/GroupMethods.java
@@ -186,12 +186,20 @@ public class GroupMethods
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
+ * NOTE: If the query string starts with the prefix {@code "group:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> parameter, but it will respect the value of
+ * <code>includeCancelled</code>. In addition, an LQL query will ignore
+ * the <code>orderBy</code> parameter, since LQL queries always return
+ * results in ID order.
+ * <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/group/search?query=... ]</code>
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled groups to
* be included. Defaults to {@code false}.
* @param offset [optional] The number of results to skip at the start
@@ -199,8 +207,9 @@ public class GroupMethods
* @param limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param orderBy [optional] The order in which to list the results.
- * This may be {@code "groupid"}, {@code "name"} (the default) or
- * {@code "title"}.
+ * This may be {@code "groupid"}, {@code "name"} (the default for non-LQL
+ * queries) or {@code "title"}. This is ignored for LQL queries, which
+ * always return results in groupid order.
* @param fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -238,12 +247,18 @@ public class GroupMethods
* Count the number of groups that would be returned by a search using
* a free text query string.
* <p>
+ * NOTE: If the query string starts with the prefix {@code "group:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> parameter, but it will respect the value of
+ * <code>includeCancelled</code>.
+ * <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/group/search-count?query=... ]</code>
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled groups to
* be included. Defaults to {@code false}.
*
diff --git a/src/java/uk/ac/cam/ucs/ibis/methods/InstitutionMethods.java b/src/java/uk/ac/cam/ucs/ibis/methods/InstitutionMethods.java
index 6849380..1657ddf 100644
--- a/src/java/uk/ac/cam/ucs/ibis/methods/InstitutionMethods.java
+++ b/src/java/uk/ac/cam/ucs/ibis/methods/InstitutionMethods.java
@@ -216,23 +216,34 @@ public class InstitutionMethods
* returned, but the optional <code>fetch</code> parameter may be used
* to fetch additional attributes or references.
* <p>
+ * NOTE: If the query string starts with the prefix {@code "inst:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> and <code>attributes</code> parameters, but
+ * it will respect the value of <code>includeCancelled</code>. In
+ * addition, an LQL query will ignore the <code>orderBy</code> parameter,
+ * since LQL queries always return results in ID order.
+ * <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/inst/search?query=... ]</code>
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled institutions
* to be included. Defaults to {@code false}.
* @param attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is {@code null} (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
* @param offset [optional] The number of results to skip at the start
* of the search. Defaults to 0.
* @param limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param orderBy [optional] The order in which to list the results.
- * This may be either {@code "instid"} or {@code "name"} (the default).
+ * This may be either {@code "instid"} or {@code "name"} (the default for
+ * non-LQL queries). This is ignored for LQL queries, which always return
+ * results in instid order.
* @param fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -272,17 +283,24 @@ public class InstitutionMethods
* Count the number of institutions that would be returned by a search
* using a free text query string.
* <p>
+ * NOTE: If the query string starts with the prefix {@code "inst:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> and <code>attributes</code> parameters, but
+ * it will respect the value of <code>includeCancelled</code>.
+ * <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/inst/search-count?query=... ]</code>
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled institutions
* to be included. Defaults to {@code false}.
* @param attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is {@code null} (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
*
* @return The number of matching institutions.
*/
diff --git a/src/java/uk/ac/cam/ucs/ibis/methods/PersonMethods.java b/src/java/uk/ac/cam/ucs/ibis/methods/PersonMethods.java
index 4b18c78..8414449 100644
--- a/src/java/uk/ac/cam/ucs/ibis/methods/PersonMethods.java
+++ b/src/java/uk/ac/cam/ucs/ibis/methods/PersonMethods.java
@@ -281,12 +281,21 @@ public class PersonMethods
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
+ * NOTE: If the query string starts with the prefix {@code "person:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> and <code>attributes</code> parameters, but
+ * it will respect the values of <code>includeCancelled</code> and
+ * <code>misStatus</code>. In addition, an LQL query will ignore the
+ * <code>orderBy</code> parameter, since LQL queries always return
+ * results in ID order.
+ * <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/person/search?query=... ]</code>
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled people to
* be included (people who are no longer members of the University).
* Defaults to {@code false}.
@@ -304,14 +313,16 @@ public class PersonMethods
* mutually exclusive.
* @param attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is {@code null} (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
* @param offset [optional] The number of results to skip at the start
* of the search. Defaults to 0.
* @param limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param orderBy [optional] The order in which to list the results.
* This may be either {@code "identifier"} or {@code "surname"} (the
- * default).
+ * default for non-LQL queries). This is ignored for LQL queries, which
+ * always return results in identifier order.
* @param fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -353,12 +364,19 @@ public class PersonMethods
* Count the number of people that would be returned by a search using
* a free text query string.
* <p>
+ * NOTE: If the query string starts with the prefix {@code "person:"}, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * <code>approxMatches</code> and <code>attributes</code> parameters, but
+ * it will respect the values of <code>includeCancelled</code> and
+ * <code>misStatus</code>.
+ * <p>
* <code style="background-color: #eec;">[ HTTP: GET /api/v1/person/search-count?query=... ]</code>
*
* @param query [required] The search string.
* @param approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to {@code false}.
+ * to {@code false}. This is ignored for LQL queries.
* @param includeCancelled [optional] Flag to allow cancelled people to
* be included (people who are no longer members of the University).
* Defaults to {@code false}.
@@ -376,7 +394,8 @@ public class PersonMethods
* mutually exclusive.
* @param attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is {@code null} (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
*
* @return The number of matching people.
*/
diff --git a/src/php/ibisclient/methods/GroupMethods.php b/src/php/ibisclient/methods/GroupMethods.php
index 68e6956..5e5b339 100644
--- a/src/php/ibisclient/methods/GroupMethods.php
+++ b/src/php/ibisclient/methods/GroupMethods.php
@@ -186,12 +186,20 @@ class GroupMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references.
*
+ * NOTE: If the query string starts with the prefix ``"group:"``, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * ``approxMatches`` parameter, but it will respect the value of
+ * ``includeCancelled``. In addition, an LQL query will ignore
+ * the ``orderBy`` parameter, since LQL queries always return
+ * results in ID order.
+ *
* ``[ HTTP: GET /api/v1/group/search?query=... ]``
*
* @param string $query [required] The search string.
* @param boolean $approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to ``false``.
+ * to ``false``. This is ignored for LQL queries.
* @param boolean $includeCancelled [optional] Flag to allow cancelled groups to
* be included. Defaults to ``false``.
* @param int $offset [optional] The number of results to skip at the start
@@ -199,8 +207,9 @@ class GroupMethods
* @param int $limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param string $orderBy [optional] The order in which to list the results.
- * This may be ``"groupid"``, ``"name"`` (the default) or
- * ``"title"``.
+ * This may be ``"groupid"``, ``"name"`` (the default for non-LQL
+ * queries) or ``"title"``. This is ignored for LQL queries, which
+ * always return results in groupid order.
* @param string $fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -237,12 +246,18 @@ class GroupMethods
* Count the number of groups that would be returned by a search using
* a free text query string.
*
+ * NOTE: If the query string starts with the prefix ``"group:"``, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * ``approxMatches`` parameter, but it will respect the value of
+ * ``includeCancelled``.
+ *
* ``[ HTTP: GET /api/v1/group/search-count?query=... ]``
*
* @param string $query [required] The search string.
* @param boolean $approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to ``false``.
+ * to ``false``. This is ignored for LQL queries.
* @param boolean $includeCancelled [optional] Flag to allow cancelled groups to
* be included. Defaults to ``false``.
*
diff --git a/src/php/ibisclient/methods/InstitutionMethods.php b/src/php/ibisclient/methods/InstitutionMethods.php
index 5f3dce0..f5122a7 100644
--- a/src/php/ibisclient/methods/InstitutionMethods.php
+++ b/src/php/ibisclient/methods/InstitutionMethods.php
@@ -211,23 +211,34 @@ class InstitutionMethods
* returned, but the optional ``fetch`` parameter may be used
* to fetch additional attributes or references.
*
+ * NOTE: If the query string starts with the prefix ``"inst:"``, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * ``approxMatches`` and ``attributes`` parameters, but
+ * it will respect the value of ``includeCancelled``. In
+ * addition, an LQL query will ignore the ``orderBy`` parameter,
+ * since LQL queries always return results in ID order.
+ *
* ``[ HTTP: GET /api/v1/inst/search?query=... ]``
*
* @param string $query [required] The search string.
* @param boolean $approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to ``false``.
+ * to ``false``. This is ignored for LQL queries.
* @param boolean $includeCancelled [optional] Flag to allow cancelled institutions
* to be included. Defaults to ``false``.
* @param string $attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is ``null`` (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
* @param int $offset [optional] The number of results to skip at the start
* of the search. Defaults to 0.
* @param int $limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param string $orderBy [optional] The order in which to list the results.
- * This may be either ``"instid"`` or ``"name"`` (the default).
+ * This may be either ``"instid"`` or ``"name"`` (the default for
+ * non-LQL queries). This is ignored for LQL queries, which always return
+ * results in instid order.
* @param string $fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -266,17 +277,24 @@ class InstitutionMethods
* Count the number of institutions that would be returned by a search
* using a free text query string.
*
+ * NOTE: If the query string starts with the prefix ``"inst:"``, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * ``approxMatches`` and ``attributes`` parameters, but
+ * it will respect the value of ``includeCancelled``.
+ *
* ``[ HTTP: GET /api/v1/inst/search-count?query=... ]``
*
* @param string $query [required] The search string.
* @param boolean $approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to ``false``.
+ * to ``false``. This is ignored for LQL queries.
* @param boolean $includeCancelled [optional] Flag to allow cancelled institutions
* to be included. Defaults to ``false``.
* @param string $attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is ``null`` (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
*
* @return int The number of matching institutions.
*/
diff --git a/src/php/ibisclient/methods/PersonMethods.php b/src/php/ibisclient/methods/PersonMethods.php
index d8fbe78..8f95428 100644
--- a/src/php/ibisclient/methods/PersonMethods.php
+++ b/src/php/ibisclient/methods/PersonMethods.php
@@ -259,12 +259,21 @@ class PersonMethods
* but the optional ``fetch`` parameter may be used to fetch
* additional attributes or references.
*
+ * NOTE: If the query string starts with the prefix ``"person:"``, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * ``approxMatches`` and ``attributes`` parameters, but
+ * it will respect the values of ``includeCancelled`` and
+ * ``misStatus``. In addition, an LQL query will ignore the
+ * ``orderBy`` parameter, since LQL queries always return
+ * results in ID order.
+ *
* ``[ HTTP: GET /api/v1/person/search?query=... ]``
*
* @param string $query [required] The search string.
* @param boolean $approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to ``false``.
+ * to ``false``. This is ignored for LQL queries.
* @param boolean $includeCancelled [optional] Flag to allow cancelled people to
* be included (people who are no longer members of the University).
* Defaults to ``false``.
@@ -283,14 +292,16 @@ class PersonMethods
* mutually exclusive.
* @param string $attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is ``null`` (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
* @param int $offset [optional] The number of results to skip at the start
* of the search. Defaults to 0.
* @param int $limit [optional] The maximum number of results to return.
* Defaults to 100.
* @param string $orderBy [optional] The order in which to list the results.
* This may be either ``"identifier"`` or ``"surname"`` (the
- * default).
+ * default for non-LQL queries). This is ignored for LQL queries, which
+ * always return results in identifier order.
* @param string $fetch [optional] A comma-separated list of any additional
* attributes or references to fetch.
*
@@ -331,12 +342,19 @@ class PersonMethods
* Count the number of people that would be returned by a search using
* a free text query string.
*
+ * NOTE: If the query string starts with the prefix ``"person:"``, it
+ * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
+ * more advanced searches. An LQL query will ignore the
+ * ``approxMatches`` and ``attributes`` parameters, but
+ * it will respect the values of ``includeCancelled`` and
+ * ``misStatus``.
+ *
* ``[ HTTP: GET /api/v1/person/search-count?query=... ]``
*
* @param string $query [required] The search string.
* @param boolean $approxMatches [optional] Flag to enable more approximate
* matching in the search, causing more results to be returned. Defaults
- * to ``false``.
+ * to ``false``. This is ignored for LQL queries.
* @param boolean $includeCancelled [optional] Flag to allow cancelled people to
* be included (people who are no longer members of the University).
* Defaults to ``false``.
@@ -355,7 +373,8 @@ class PersonMethods
* mutually exclusive.
* @param string $attributes [optional] A comma-separated list of attributes to
* consider when searching. If this is ``null`` (the default) then
- * all attribute schemes marked as searchable will be included.
+ * all attribute schemes marked as searchable will be included. This is
+ * ignored for LQL queries.
*
* @return int The number of matching people.
*/
diff --git a/src/python/ibisclient/methods.py b/src/python/ibisclient/methods.py
index fbcf345..8736859 100644
--- a/src/python/ibisclient/methods.py
+++ b/src/python/ibisclient/methods.py
@@ -224,6 +224,15 @@ class GroupMethods:
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
+ .. note::
+ If the query string starts with the prefix ``"group:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` parameter, but it will respect the value of
+ `includeCancelled`. In addition, an LQL query will ignore
+ the `orderBy` parameter, since LQL queries always return
+ results in ID order.
+
``[ HTTP: GET /api/v1/group/search?query=... ]``
**Parameters**
@@ -233,7 +242,7 @@ class GroupMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled groups to
@@ -249,8 +258,9 @@ class GroupMethods:
`orderBy` : str
[optional] The order in which to list the results.
- This may be ``"groupid"``, ``"name"`` (the default) or
- ``"title"``.
+ This may be ``"groupid"``, ``"name"`` (the default for non-LQL
+ queries) or ``"title"``. This is ignored for LQL queries, which
+ always return results in groupid order.
`fetch` : str
[optional] A comma-separated list of any additional
@@ -284,6 +294,13 @@ class GroupMethods:
Count the number of groups that would be returned by a search using
a free text query string.
+ .. note::
+ If the query string starts with the prefix ``"group:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` parameter, but it will respect the value of
+ `includeCancelled`.
+
``[ HTTP: GET /api/v1/group/search-count?query=... ]``
**Parameters**
@@ -293,7 +310,7 @@ class GroupMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled groups to
@@ -743,6 +760,15 @@ class InstitutionMethods:
returned, but the optional `fetch` parameter may be used
to fetch additional attributes or references.
+ .. note::
+ If the query string starts with the prefix ``"inst:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` and `attributes` parameters, but
+ it will respect the value of `includeCancelled`. In
+ addition, an LQL query will ignore the `orderBy` parameter,
+ since LQL queries always return results in ID order.
+
``[ HTTP: GET /api/v1/inst/search?query=... ]``
**Parameters**
@@ -752,7 +778,7 @@ class InstitutionMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled institutions
@@ -761,7 +787,8 @@ class InstitutionMethods:
`attributes` : str
[optional] A comma-separated list of attributes to
consider when searching. If this is :any:`None` (the default) then
- all attribute schemes marked as searchable will be included.
+ all attribute schemes marked as searchable will be included. This is
+ ignored for LQL queries.
`offset` : int
[optional] The number of results to skip at the start
@@ -773,7 +800,9 @@ class InstitutionMethods:
`orderBy` : str
[optional] The order in which to list the results.
- This may be either ``"instid"`` or ``"name"`` (the default).
+ This may be either ``"instid"`` or ``"name"`` (the default for
+ non-LQL queries). This is ignored for LQL queries, which always return
+ results in instid order.
`fetch` : str
[optional] A comma-separated list of any additional
@@ -809,6 +838,13 @@ class InstitutionMethods:
Count the number of institutions that would be returned by a search
using a free text query string.
+ .. note::
+ If the query string starts with the prefix ``"inst:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` and `attributes` parameters, but
+ it will respect the value of `includeCancelled`.
+
``[ HTTP: GET /api/v1/inst/search-count?query=... ]``
**Parameters**
@@ -818,7 +854,7 @@ class InstitutionMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled institutions
@@ -827,7 +863,8 @@ class InstitutionMethods:
`attributes` : str
[optional] A comma-separated list of attributes to
consider when searching. If this is :any:`None` (the default) then
- all attribute schemes marked as searchable will be included.
+ all attribute schemes marked as searchable will be included. This is
+ ignored for LQL queries.
**Returns**
int
@@ -1466,6 +1503,16 @@ class PersonMethods:
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
+ .. note::
+ If the query string starts with the prefix ``"person:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` and `attributes` parameters, but
+ it will respect the values of `includeCancelled` and
+ `misStatus`. In addition, an LQL query will ignore the
+ `orderBy` parameter, since LQL queries always return
+ results in ID order.
+
``[ HTTP: GET /api/v1/person/search?query=... ]``
**Parameters**
@@ -1475,7 +1522,7 @@ class PersonMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled people to
@@ -1500,7 +1547,8 @@ class PersonMethods:
`attributes` : str
[optional] A comma-separated list of attributes to
consider when searching. If this is :any:`None` (the default) then
- all attribute schemes marked as searchable will be included.
+ all attribute schemes marked as searchable will be included. This is
+ ignored for LQL queries.
`offset` : int
[optional] The number of results to skip at the start
@@ -1513,7 +1561,8 @@ class PersonMethods:
`orderBy` : str
[optional] The order in which to list the results.
This may be either ``"identifier"`` or ``"surname"`` (the
- default).
+ default for non-LQL queries). This is ignored for LQL queries, which
+ always return results in identifier order.
`fetch` : str
[optional] A comma-separated list of any additional
@@ -1551,6 +1600,14 @@ class PersonMethods:
Count the number of people that would be returned by a search using
a free text query string.
+ .. note::
+ If the query string starts with the prefix ``"person:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` and `attributes` parameters, but
+ it will respect the values of `includeCancelled` and
+ `misStatus`.
+
``[ HTTP: GET /api/v1/person/search-count?query=... ]``
**Parameters**
@@ -1560,7 +1617,7 @@ class PersonMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled people to
@@ -1585,7 +1642,8 @@ class PersonMethods:
`attributes` : str
[optional] A comma-separated list of attributes to
consider when searching. If this is :any:`None` (the default) then
- all attribute schemes marked as searchable will be included.
+ all attribute schemes marked as searchable will be included. This is
+ ignored for LQL queries.
**Returns**
int
diff --git a/src/python3/ibisclient/methods.py b/src/python3/ibisclient/methods.py
index 724f8ad..7c37913 100644
--- a/src/python3/ibisclient/methods.py
+++ b/src/python3/ibisclient/methods.py
@@ -224,6 +224,15 @@ class GroupMethods:
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
+ .. note::
+ If the query string starts with the prefix ``"group:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` parameter, but it will respect the value of
+ `includeCancelled`. In addition, an LQL query will ignore
+ the `orderBy` parameter, since LQL queries always return
+ results in ID order.
+
``[ HTTP: GET /api/v1/group/search?query=... ]``
**Parameters**
@@ -233,7 +242,7 @@ class GroupMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled groups to
@@ -249,8 +258,9 @@ class GroupMethods:
`orderBy` : str
[optional] The order in which to list the results.
- This may be ``"groupid"``, ``"name"`` (the default) or
- ``"title"``.
+ This may be ``"groupid"``, ``"name"`` (the default for non-LQL
+ queries) or ``"title"``. This is ignored for LQL queries, which
+ always return results in groupid order.
`fetch` : str
[optional] A comma-separated list of any additional
@@ -284,6 +294,13 @@ class GroupMethods:
Count the number of groups that would be returned by a search using
a free text query string.
+ .. note::
+ If the query string starts with the prefix ``"group:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` parameter, but it will respect the value of
+ `includeCancelled`.
+
``[ HTTP: GET /api/v1/group/search-count?query=... ]``
**Parameters**
@@ -293,7 +310,7 @@ class GroupMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled groups to
@@ -743,6 +760,15 @@ class InstitutionMethods:
returned, but the optional `fetch` parameter may be used
to fetch additional attributes or references.
+ .. note::
+ If the query string starts with the prefix ``"inst:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` and `attributes` parameters, but
+ it will respect the value of `includeCancelled`. In
+ addition, an LQL query will ignore the `orderBy` parameter,
+ since LQL queries always return results in ID order.
+
``[ HTTP: GET /api/v1/inst/search?query=... ]``
**Parameters**
@@ -752,7 +778,7 @@ class InstitutionMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled institutions
@@ -761,7 +787,8 @@ class InstitutionMethods:
`attributes` : str
[optional] A comma-separated list of attributes to
consider when searching. If this is :any:`None` (the default) then
- all attribute schemes marked as searchable will be included.
+ all attribute schemes marked as searchable will be included. This is
+ ignored for LQL queries.
`offset` : int
[optional] The number of results to skip at the start
@@ -773,7 +800,9 @@ class InstitutionMethods:
`orderBy` : str
[optional] The order in which to list the results.
- This may be either ``"instid"`` or ``"name"`` (the default).
+ This may be either ``"instid"`` or ``"name"`` (the default for
+ non-LQL queries). This is ignored for LQL queries, which always return
+ results in instid order.
`fetch` : str
[optional] A comma-separated list of any additional
@@ -809,6 +838,13 @@ class InstitutionMethods:
Count the number of institutions that would be returned by a search
using a free text query string.
+ .. note::
+ If the query string starts with the prefix ``"inst:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` and `attributes` parameters, but
+ it will respect the value of `includeCancelled`.
+
``[ HTTP: GET /api/v1/inst/search-count?query=... ]``
**Parameters**
@@ -818,7 +854,7 @@ class InstitutionMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled institutions
@@ -827,7 +863,8 @@ class InstitutionMethods:
`attributes` : str
[optional] A comma-separated list of attributes to
consider when searching. If this is :any:`None` (the default) then
- all attribute schemes marked as searchable will be included.
+ all attribute schemes marked as searchable will be included. This is
+ ignored for LQL queries.
**Returns**
int
@@ -1466,6 +1503,16 @@ class PersonMethods:
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
+ .. note::
+ If the query string starts with the prefix ``"person:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` and `attributes` parameters, but
+ it will respect the values of `includeCancelled` and
+ `misStatus`. In addition, an LQL query will ignore the
+ `orderBy` parameter, since LQL queries always return
+ results in ID order.
+
``[ HTTP: GET /api/v1/person/search?query=... ]``
**Parameters**
@@ -1475,7 +1522,7 @@ class PersonMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled people to
@@ -1500,7 +1547,8 @@ class PersonMethods:
`attributes` : str
[optional] A comma-separated list of attributes to
consider when searching. If this is :any:`None` (the default) then
- all attribute schemes marked as searchable will be included.
+ all attribute schemes marked as searchable will be included. This is
+ ignored for LQL queries.
`offset` : int
[optional] The number of results to skip at the start
@@ -1513,7 +1561,8 @@ class PersonMethods:
`orderBy` : str
[optional] The order in which to list the results.
This may be either ``"identifier"`` or ``"surname"`` (the
- default).
+ default for non-LQL queries). This is ignored for LQL queries, which
+ always return results in identifier order.
`fetch` : str
[optional] A comma-separated list of any additional
@@ -1551,6 +1600,14 @@ class PersonMethods:
Count the number of people that would be returned by a search using
a free text query string.
+ .. note::
+ If the query string starts with the prefix ``"person:"``, it
+ is treated as an `LQL query </lql>`_, allowing
+ more advanced searches. An LQL query will ignore the
+ `approxMatches` and `attributes` parameters, but
+ it will respect the values of `includeCancelled` and
+ `misStatus`.
+
``[ HTTP: GET /api/v1/person/search-count?query=... ]``
**Parameters**
@@ -1560,7 +1617,7 @@ class PersonMethods:
`approxMatches` : bool
[optional] Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
- to :any:`False`.
+ to :any:`False`. This is ignored for LQL queries.
`includeCancelled` : bool
[optional] Flag to allow cancelled people to
@@ -1585,7 +1642,8 @@ class PersonMethods:
`attributes` : str
[optional] A comma-separated list of attributes to
consider when searching. If this is :any:`None` (the default) then
- all attribute schemes marked as searchable will be included.
+ all attribute schemes marked as searchable will be included. This is
+ ignored for LQL queries.
**Returns**
int
--
GitLab