diff options
Diffstat (limited to 'help/yacysearch.md')
| -rw-r--r-- | help/yacysearch.md | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/help/yacysearch.md b/help/yacysearch.md new file mode 100644 index 000000000..36181f950 --- /dev/null +++ b/help/yacysearch.md @@ -0,0 +1,102 @@ +--- +page: htroot/yacysearch.html +help: help/yacysearch.md +title: Search Page +package: core-search-public +access: mixed +kind: search-page +backend_java: source/net/yacy/htroot/yacysearch.java +--- + +# Search Page + +## Purpose + +The Search Page is the main result page. It turns a query into local or distributed search results and carries the parameters that define result count, content type, language, pagination, and verification behavior. + +Use it to understand how a browser search maps to an API-style request. + +## What You Can Do Here + +- Search the local YaCy index, or the YaCy network when the peer is configured for global search. +- Choose query, result type, collection, and verification options according to the information need. +- Page through results, restrict results to a URL pattern, request a content type such as images or text, and choose how fresh snippets must be. +- When authenticated, perform result actions such as deleting a reference, recommending a result, bookmarking it, or sending a URL to a blacklist. + +## Page Architecture + +Public search pages turn request parameters into result lists, previews, snippets, feeds, or integration fragments. They are mostly read-oriented, but some result actions can bookmark, recommend, blacklist, or delete references when authenticated. + +| Control | Meaning | Values or examples | +| --- | --- | --- | +| `query` | Search text. Use ordinary search terms, quoted phrases where supported by YaCy query parsing, and optional YaCy modifiers such as collection filters when you intentionally need them. | Search terms, for example `climate data` or a more specific phrase. | +| `Enter` | Browser submit button. Omit it from direct API calls; YaCy uses the query and filter parameters, not the button label, to run the search. | Browser-generated submit value only. | + +## Correct Use + +For a normal search, send only `query` and the options that express the user intent: `maximumRecords` for result count, `resource` for local versus network search, `contentdom` for text or media, and `urlmaskfilter` when the user asks to search inside a site. Start with `verify=iffresh` when freshness matters; use `cacheonly` only when the user explicitly wants stored snippets without refetching. + +Do not send result-action parameters such as `deleteref`, `bookmarkref`, or `blacklisturl` as part of an ordinary search. Those parameters change state and require an exact result reference from a prior response. + +## Access And Safety + +The page may be visible, but the backend performs authentication checks for protected actions. + +Protected related endpoint(s): `/yacysearch.html`. + +Backend checks: administrator authentication, user authentication. + +## Automation And API + +Page backend: `source/net/yacy/htroot/yacysearch.java`. + +| Endpoint | Method | Access | Backend | +| --- | --- | --- | --- | +| `/yacysearch.html` | `GET` | mixed | `source/net/yacy/htroot/yacysearch.java` | + +### Parameter Guide + +The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default. Low-level generated parameters are omitted when they are only meaningful inside the rendered YaCy form. + +| Parameter | Meaning and valid values | Care | +| --- | --- | --- | +| `query` | Search text. Use ordinary search terms, quoted phrases where supported by YaCy query parsing, and optional YaCy modifiers such as collection filters when you intentionally need them. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `auth` | Requests authentication-aware behavior when the endpoint supports user-specific or protected actions. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `callback` | JSONP callback name for legacy script clients. Leave empty for normal HTML or JSON-style use. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `collection` | Collection name. Use it to group crawled or imported documents and to search or manage that group later. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `constraint` | Encoded YaCy bitfield constraint. Leave it empty unless you are replaying a URL generated by YaCy itself. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `contentdom` | Content domain filter. Common values are `all`, `text`, `image`, `audio`, `video`, and `app`; use it to ask for web pages, media, or application documents deliberately. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `count` | SRU-style result count. It is an alternative to `maximumRecords` on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `deleteref` | URL hash/reference selected for deletion from results. Use only with administrator intent and an exact known reference. | Can remove data, stop work, expose access, or make a broad operational change. Use only with explicit confirmation and an exact target. | +| `focus` | Browser presentation flag controlling whether the search input receives focus. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `indexof` | Interprets the query as an index-of style request when supported. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `lr` | Language filter, usually a two-letter code such as `de`, `fr`, or `en` when the page supports language-restricted search. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `maximumRecords` | Maximum number of results to return on one page. Use a modest value for interactive use; larger values are for controlled scripts. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `nav` | Navigator/facet selection for search results. `all` requests the normal set; narrower values reduce displayed facets. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `offset` | Zero-based result offset for pagination. | Read-only pagination control. Use `0` for the first page and increase by the result count for later pages. | +| `prefermaskfilter` | Regular-expression URL preference. Matching results are favored without excluding all others. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `recommendref` | URL hash/reference selected for recommendation. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `resortCachedResults` | Requests resorting of a cached search event instead of starting a fully fresh result event. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `resource` | Search source. `local` searches this peer index; `global` may use the YaCy network when the peer and configuration allow it. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `resource-switch` | Browser control for switching between local and global search. For direct calls use `resource=local` or `resource=global`. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `rows` | Rows requested by API-style clients. It is another result-count alias on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `search` | Alternative search text parameter accepted by some search endpoints; prefer `query` on browser search pages unless reproducing an existing URL. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `startRecord` | First result record for pagination; accepted as an alternative to `offset` on search endpoints. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `strictContentDom` | When true, YaCy enforces the selected content domain more strictly instead of using it mainly for presentation. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | +| `timezoneOffset` | Client timezone offset in minutes. YaCy uses it for date display or schedule calculations. | Read-only context for date handling; it does not by itself change the index. | +| `urlmaskfilter` | Regular-expression URL filter for search results. Use `.*` for no restriction; use a precise host/path expression to search inside a site or section. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. | +| `verify` | Snippet/cache verification strategy. Typical values are `iffresh`, `ifexist`, `cacheonly`, `nocache`, and `false`; choose according to whether freshness or speed matters more. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. | + +Example request shape: + +```http +GET /yacysearch.html?query=climate+data&maximumRecords=10&resource=local&contentdom=text&verify=iffresh +``` + +## What To Expect + +The response is an HTML result page. It contains result entries, navigators/facets when enabled, and hidden references used by authenticated result actions. If a query returns too little, first check whether the crawler has indexed the relevant site and whether `urlmaskfilter`, `collection`, or `contentdom` narrowed the request too far. + +## Related Pages + +- `Status.html` |