From de98840e0e4d94955ec099ee079b49078e62ba9a Mon Sep 17 00:00:00 2001 From: Ian Murray Date: Mon, 21 May 2012 09:54:52 +0100 Subject: [PATCH 1/3] [#2345] Docstring for package_search action. --- ckan/logic/action/get.py | 89 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/ckan/logic/action/get.py b/ckan/logic/action/get.py index cc303f48144..a148ffb2ec6 100644 --- a/ckan/logic/action/get.py +++ b/ckan/logic/action/get.py @@ -837,6 +837,95 @@ def user_autocomplete(context, data_dict): return user_list def package_search(context, data_dict): + ''' + Searches for packages satisfying a given search criteria. + + This action accepts solr search query parameters (details below), and + returns a dictionary of results, including dictized datasets that match + the search criteria, a search count and also facet information. + + Solr Parameters: + + For more in depth treatment of each paramter, please read the `Solr + Documentation `_. + + This action accepts a *subset* of solr's search query parameters: + + :param q: the solr query. Optional. Default: `"*:*"` + :type q: string + :param fq: any filter queries to apply. Note: `+site_id:{ckan_site_id}` + is added to this string prior to the query being executed. + :type fq: string + :param rows: the number of matching rows to return. + :type rows: int + :param sort: sorting of the search results. Optional. Default: + "score desc, name asc". As per the solr documentation, this is a + comma-separated string of field names and sort-orderings. + :type sort: string + :param start: the offset in the complete result for where the set of + returned datasets should begin. + :type start: int + :param qf: the dismax query fields to search within, including boosts. See + the `Solr Dismax + Documentation`_ + for further details. + :type qf: string + :param facet: whether to enable faceted results. Default: "true". + :type facet: string + :param facet.mincount: the minimum counts for facet fields should be + included in the results. + :type facet.mincount: int + :param facet.limit: the maximum number of constraint counts that should be + returned for the facet fields. A negative value means unlimited + :type facet.limit: int + :param facet.field: the fields to facet upon. Default empty. If empty, + then the returned facet information is empty. + :type facet.field: list of strings + + Results: + + The result of this action is a dict with the following keys: + + :param count: the number of results found. Note, this is the total number + of results found, not the total number of results returned (which is + affected by limit and row parameters used in the input). + :type count: int + :param results: ordered list of datasets matching the query, where the + ordering defined by the sort parameter used in the query. + :type results: list of dictized datasets. + :param search_facets: aggregated information about facet counts. The outer + dict is keyed by the facet field name (as used in the search query). + Each entry of the outer dict is itself a dict, with a "title" key, and + an "items" key. The "items" key's value is a list of dicts, each with + "count", "display_name" and "name" entries. The display_name is a + form of the name that can be used in titles. + :type search_facets: nested dict of dicts. + + An example result: :: + + {'count': 2, + 'results': [ { }, { }], + 'search_facets': {u'tags': {'items': [{'count': 1, + 'display_name': u'tolstoy', + 'name': u'tolstoy'}, + {'count': 2, + 'display_name': u'russian', + 'name': u'russian'} + ] + } + } + } + + Limitations: + + The full solr query language is not exposed, including. + + fl + The parameter that controls which fields are returned in the solr + query cannot be changed. CKAN always returns the matched datasets as + dictionary objects. + + ''' model = context['model'] session = context['session'] user = context['user'] From 9248ce2b508597c034a4fab831af15b66700100b Mon Sep 17 00:00:00 2001 From: Ian Murray Date: Mon, 21 May 2012 10:09:10 +0100 Subject: [PATCH 2/3] Tidying package_search docstring --- ckan/logic/action/get.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/ckan/logic/action/get.py b/ckan/logic/action/get.py index a72fdd179d0..64881425b1b 100644 --- a/ckan/logic/action/get.py +++ b/ckan/logic/action/get.py @@ -1005,7 +1005,7 @@ def package_search(context, data_dict): returns a dictionary of results, including dictized datasets that match the search criteria, a search count and also facet information. - Solr Parameters: + **Solr Parameters:** For more in depth treatment of each paramter, please read the `Solr Documentation `_. @@ -1027,7 +1027,7 @@ def package_search(context, data_dict): returned datasets should begin. :type start: int :param qf: the dismax query fields to search within, including boosts. See - the `Solr Dismax Documentation + the `Solr Dismax Documentation `_ for further details. :type qf: string @@ -1043,10 +1043,11 @@ def package_search(context, data_dict): then the returned facet information is empty. :type facet.field: list of strings - Results: + **Results:** The result of this action is a dict with the following keys: + :rtype: A dictionary with the following keys :param count: the number of results found. Note, this is the total number of results found, not the total number of results returned (which is affected by limit and row parameters used in the input). @@ -1077,7 +1078,7 @@ def package_search(context, data_dict): } } - Limitations: + **Limitations:** The full solr query language is not exposed, including. From e5a1ccff8a28bb9979d11525466ae58b94ef7d1c Mon Sep 17 00:00:00 2001 From: Ian Murray Date: Mon, 21 May 2012 10:18:32 +0100 Subject: [PATCH 3/3] Moved section about GETable actions --- doc/apiv3.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/doc/apiv3.rst b/doc/apiv3.rst index 9f7db24e670..a76c6be6e00 100644 --- a/doc/apiv3.rst +++ b/doc/apiv3.rst @@ -57,25 +57,8 @@ Examples:: curl http://test.ckan.net/api/action/package_list -d '{}' curl http://test.ckan.net/api/action/package_show -d '{"id": "fd788e57-dce4-481c-832d-497235bf9f78"}' -Actions -======= - -.. automodule:: ckan.logic.action.get - :members: - -.. automodule:: ckan.logic.action.create - :members: - -.. automodule:: ckan.logic.action.update - :members: - -.. automodule:: ckan.logic.action.delete - :members: - -In case of doubt, refer to the code of the logic actions, which is found in the CKAN source in the ``ckan/logic/action`` directory. - GET-able Actions ----------------- +................ Actions defined in get.py can also be accessed with a GET request **in addition** to the POST method described just above. @@ -112,6 +95,23 @@ consequence of this, currently the *resource_search*, *tag_search* and Also, it is worth bearing this limitation in mind when creating your own actions via the `IActions` interface. +Actions +======= + +.. automodule:: ckan.logic.action.get + :members: + +.. automodule:: ckan.logic.action.create + :members: + +.. automodule:: ckan.logic.action.update + :members: + +.. automodule:: ckan.logic.action.delete + :members: + +In case of doubt, refer to the code of the logic actions, which is found in the CKAN source in the ``ckan/logic/action`` directory. + Responses =========