Version 1 of 1 · · razie · in person · Current version

name
d3-f-search
description
Search — finding topics by words and tags in one project or across all of a person's projects, inherited Help and skills in results, and the other search boxes (settings, pipeline). Get skills only from /api/v2/skills/d3.
feature
srch
concepts
[search]
tags
#skill #feature #d3skill #wip

d3-f-search

Intro

Finding topics by words and tags.

Search finds topics by words and tags, in one project or across every project a person belongs to, including inherited Help and skills. Settings and the pipeline have their own search. Tags are d3-f-tags. Spec: SpecUi › ui-menus (^srch-n).

Essentials

  • R-search-1 Prefer one search call to listing and reading topics one by one.
  • R-search-2 Results follow each project's view rules: you only see what you may read; Report topics are never searched.

Concepts

A ranked query over topics: name matches first, then mentions, most matches first; then inherited content. Also called: find, look up. Fields (hit): topic, project, its URL; pending (projects that timed out, scope=mine).

search_query

  • Summary: one call by words (and #tags) in this project.
  • When: finding anything in the project.
  • Needs: the words.
  • Call: GET /api/v2/search?q=<words> Also: tags in the query: #gold nevada = tagged gold and mentioning nevada · tags alone: GET /api/v2/topics?tag=gold (case ignored).
  • Rules: R-search-1, R-search-2. After the project's own results comes one group per base (nearest first) with the Help, skills and templates it inherits, each marked with its project.
  • Errors: E_ARG → empty query: send q.
  • Gotchas: Nothing found that should be there: it may be a Report topic (not searched), notlisted (d3-f-tags › tag_diagnose), or in a project you aren't a member of.

search_mine

  • Summary: search every project you're a member of, merged by score.
  • When: the subject may live in another of your person's projects.
  • Needs: —
  • Call: GET /api/v2/search?q=<words>&scope=mine → hits with project and URL; timed-out projects in pending.
  • Rules: Each project under its own view rules.
  • Errors: E_ARG.
  • Gotchas: —

search_settings

  • Summary: settings search returns a page › tab › setting tree.
  • When: finding where a setting lives.
  • Needs: the words.
  • Call: GET /api/v2/settings/search?q=.
  • Rules: Only what the caller may reach.
  • Errors: —
  • Gotchas: —

search_forPerson

  • Summary: the search boxes people use, to point them at.
  • When: telling a person how to find something themselves.
  • Needs: —
  • Call: the box next to the logo on every page (This project | All my projects toggle; all: before the query does the same) Also: the pipeline page's box (any word in title, summary, document or notes; an item's number opens it) · the topic List view's filter (name, title, first sentence and tags; #tag matches tags only).
  • Rules: —
  • Errors: —
  • Gotchas: —

Errors

  • E_ARG — an empty query → send q. see #search_query
  • Nothing found that should be there — a Report, notlisted, or a project you aren't in. see #search_query