Merge branch 'MDL-68664-310' of git://github.com/lameze/moodle into MOODLE_310_STABLE
[moodle.git] / search / upgrade.txt
CommitLineData
5f654ea2
DM
1This files describes API changes in /search/*,
2information provided here is intended especially for developers.
3
fe9ecef9 4=== 3.10 ===
0deb1946 5
6* Search indexing now supports sending multiple documents to the server in a batch. This is implemented
7 for the Solr search engine, where it significantly increases performance. For this to work, engines
8 should implement add_document_batch() function and return true to supports_add_document_batch().
9 There is also an additional parameter returned from add_documents() with the number of batches
10 sent, which is used for the log display. Existing engines should continue to work unmodified.
679e8d8b 11* Search engines can now implement the optional has_alternate_configuration() function to indicate
12 if they provide two different connection configurations (for use when moving between two search
13 engines of the same type). The constructor should also accept a boolean value (true = alternate);
14 passing this to the base class constructor will automatically switch in the alternate
15 configuration settings, provided they begin with 'alternate'.
0deb1946 16
c5b2f2b3
AA
17=== 3.8 ===
18
19* Search indexing supports time limits to make the scheduled task run more neatly since 3.4. In order for
20 this to work, search engine plugins will need to implement the 'stopat' parameter if they
21 override the add_documents() function, and return an extra parameter from this function (see base
22 class in engine.php). Unmodified plugins will not work anymore.
7ba2a201 23* New search engine functions delete_index_for_context and delete_index_for_course are called by
24 the search manager to inform the search engine it can remove some documents from its index.
25 (Otherwise, documents from delete courses are never removed unless you reindex.) It is optional
26 for search engines to support these; if they don't implement them then behaviour is unchanged.
c5b2f2b3 27
2085e860
DM
28=== 3.7 ===
29
30* Search areas now have categories and can optionally implement get_category_names method to
31 display search results of the area in the required tab on the search results screen (if this
32 feature is enabled).
33* Added a new call back search_area_categories. Plugins can implement this method in lib.php and
34 return a list of custom search area categories (\core_search\area_category) and associated with
35 them search areas. This will bring additional custom tabs to the search results screen.
36* Added \core_search\manager::clean_up_non_existing_area method to clean up removed or renamed
37 search areas. To support that a new adhoc task core\task\clean_up_deleted_search_area_task
38 added.
39
25564a78 40=== 3.5 ===
41
42* Search areas may now optionally implement the get_contexts_to_reindex function (for modules and
43 blocks, see also get_contexts_to_reindex_extra_sql). This allows a search area to customise the
44 order in which it is reindexed when doing a gradual reindex, so as to reindex the most important
65da6840 45 contexts first. If not implemented, the default behaviour for modules and blocks is to reindex
46 the newest items first; for other types of search area it will just index the whole system
47 context, oldest data first.
fc440796 48* Search engines may now implement get_supported_orders function to provide multiple ordering
49 options (other than 'relevance' which is default). If there is more than one order then a choice
50 will be shown to users. (This is an optional feature, existing search engine plugins do not need
51 to be modified in order to continue working.)
4359ef18 52* Module search areas that wish to support group filtering should set the new optional search
53 document field groupid (note: to remain compatible with earlier versions, do this inside an if
54 statement so that it only happens on 3.4+) and return true to the supports_group_restriction
55 function. See documentation in \core_search\base_mod class and example in \mod_forum\search\post.
4359ef18 56* When a search engine supports group filtering, the \core_search\manager::search function now
57 accepts the optional 'groupids' parameter in its $data input. This parameter is an array of one
58 or more group IDs. If supplied, only results from those groups will be returned.
4359ef18 59* Search engine plugins will need to be be modified if they wish to support group filtering.
60 (Search engines should continue to work unmodified, but will not then support group filtering.)
61 The modification steps are:
62 - Implement the new update_schema function to make the schema change (add groupid field).
63 - Ensure that the groupid field is stored correctly when provided in a document while indexing.
64 - Return true to new supports_group_filtering() function.
65 - execute_query should support the new $data->groupids parameter (to allow users to restrict
66 search results to specific groups) and the modified meaning of the second parameter,
67 $accessinfo (to automatically restrict search results users cannot access due to groups).
68 See implementation in Solr search engine.
73fd5666 69* Search engine plugins can optionally use a new $this->should_skip_schema_check() function to
70 decide when to skip slow schema checking inside the is_server_ready function, improving user
71 performance on the search page. The Solr plugin implements this.
72* API function \core_search\manager::instance() now includes a $fast parameter to skip schema
73 checks (as above).
4359ef18 74
222a97ce 75* Search engines should now implement the 'userids' option to restrict search results to those from
76 specific users, and return true to the new supports_users() function. The supplied Solr search
77 engine includes this feature. If this is not implemented, the search engine will continue to work
78 but the 'Users' search option will not appear.
79
67d64795 80=== 3.4 ===
81
82* Search indexing now supports time limits to make the scheduled task run more neatly. In order for
83 this to work, search engine plugins will need to implement the 'stopat' parameter if they
84 override the add_documents() function, and return an extra parameter from this function (see base
85 class in engine.php). Unmodified plugins will still work, but without supporting time limits.
427b7563 86* Search areas should now implement the get_document_recordset function instead of the old
87 get_recordset_by_timestamp API (implement both if the area should work in older Moodle versions
88 as well). The new function is the same as the old one, but has an additional context parameter.
89 There is a helper function get_context_restriction_sql to make this easy to implement; see code
90 in base_activity.php for an example of how to implement this in your search area. (The
91 change was required to make search work after restoring sites. It also allows more flexible
92 reindexing in other cases.)
67d64795 93
5f654ea2
DM
94=== 3.2 ===
95
96* Base search area classes have been renamed, please update your search areas to use the classes below:
97 - \core_search\area\base has been renamed to \core_search\base
98 - \core_search\area\base_mod has been renamed to \core_search\base_mod
99 - \core_search\area\base_activity has been renamed to \core_search\base_activity