ontology-lookup 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1051 @@
1
+ Metadata-Version: 2.4
2
+ Name: ontology-lookup
3
+ Version: 0.1.1
4
+ Summary: High-performance, size-optimized local ontology lookup engine
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: fastapi>=0.100.0
8
+ Requires-Dist: uvicorn>=0.20.0
9
+ Requires-Dist: pydantic>=2.0.0
10
+ Requires-Dist: ijson>=3.3.0
11
+ Requires-Dist: python-dotenv>=1.0.0
12
+ Requires-Dist: cachetools>=5.3.0
13
+ Provides-Extra: dev
14
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
15
+ Requires-Dist: httpx>=0.27.0; extra == "dev"
16
+ Requires-Dist: ruff>=0.4.0; extra == "dev"
17
+
18
+ # Ontology Lookup: High-Performance Multi-Ontology Engine
19
+
20
+ A high-performance, size-optimized local ontology lookup engine, Python library, and REST API built with **Python**, **SQLite (FTS5 + WAL)**, and **FastAPI**.
21
+
22
+ Designed for biological and scientific ontologies (such as HUPO PSI-MS, EDAM, OBI, GO, EFO, ChEBI, CL, DOID) hosted on EMBL-EBI OLS4 or OBO Foundry, this engine provides sub-millisecond, case-insensitive query resolution, hierarchical graph traversal, and concurrent read scalability.
23
+
24
+ ---
25
+
26
+ ## Table of Contents
27
+
28
+ 1. [Installation, Development and Test](#installation-development-and-test)
29
+ 2. [Architecture and Design](#architecture-and-design)
30
+ 3. [Download ontology sources from OLS4](#download-ontology-sources-from-ols4)
31
+ 4. [Build Multi-ontology Lookup Database](#build-multi-ontology-lookup-database)
32
+ - [CLI Commands](#cli-build-and-database-management)
33
+ - [Create Database](#1-create-database-cli)
34
+ - [Add Ontologies](#2-add-ontologies-cli)
35
+ - [Delete Ontologies](#3-delete-ontologies-cli)
36
+ - [Add, Update, and Delete Term Tags](#4-addupdatedelete-term-tags-cli)
37
+ - [Inspect Database and Ontologies](#5-inspect-database-and-ontologies-cli)
38
+ - [Python API](#python-api-build-and-database-management)
39
+ - [Create Database](#1-create-database-api)
40
+ - [Add Ontologies](#2-add-ontologies-api)
41
+ - [Delete Ontologies](#3-delete-ontologies-api)
42
+ - [Add, Update, and Delete Term Tags](#4-addupdatedelete-term-tags-api)
43
+ - [Inspect Database and Ontologies](#5-inspect-database-and-ontologies-api)
44
+ 5. [Search on Multi-ontology Lookup Database](#search-on-multi-ontology-lookup-database)
45
+ - [Starting the REST API Server](#starting-the-rest-api-server)
46
+ - [API Endpoints Reference Table](#api-endpoints-reference-table)
47
+ - [Use Case 1: Term Lookup by CURIE or IRI (Accession)](#use-case-1-term-lookup-by-curie-or-iri-accession)
48
+ - [Use Case 2: Exact Label Match](#use-case-2-exact-label-match)
49
+ - [Use Case 3: Exact Match Search across Labels and Synonyms](#use-case-3-exact-match-search-across-labels-and-synonyms)
50
+ - [Use Case 4: Hierarchy-Constrained Search (Parent CURIE Filter)](#use-case-4-hierarchy-constrained-search-parent-curie-filter)
51
+ - [Use Case 5: CURIE and IRI Resolution](#use-case-5-curie-and-iri-resolution)
52
+ - [Use Case 6: Key-Value Metadata Tag Search](#use-case-6-key-value-metadata-tag-search)
53
+ - [Use Case 7: Recursive Descendants / Children Lookup](#use-case-7-recursive-descendants--children-lookup)
54
+ - [Use Case 8: Freetext Search (Labels, Synonyms, and Definitions)](#use-case-8-freetext-search-labels-synonyms-and-definitions)
55
+
56
+ ---
57
+
58
+ ## Installation, Development and Test
59
+
60
+ This project requires **Python >= 3.10** and uses [`uv`](https://docs.astral.sh/uv/) for fast, reproducible dependency management and environment isolation.
61
+
62
+ ### 1. Installation
63
+
64
+ Clone the repository and install all dependencies:
65
+
66
+ ```bash
67
+ # Clone the repository
68
+ git clone https://github.com/your-org/ontology_lookup.git
69
+ cd ontology_lookup
70
+
71
+ # Sync virtual environment and install dependencies with uv
72
+ uv sync
73
+ ```
74
+
75
+ Alternatively, install in development mode with standard `pip`:
76
+
77
+ ```bash
78
+ pip install -e ".[dev]"
79
+ ```
80
+
81
+ ### 2. Environment Configuration
82
+
83
+ Default paths and ingestion parameters are managed via a `.env` file. Copy `.env.example` to start:
84
+
85
+ ```bash
86
+ cp .env.example .env
87
+ ```
88
+
89
+ Configurable variables:
90
+
91
+ | Variable | Default Value | Description |
92
+ | --- | --- | --- |
93
+ | `ONTOLOGY_SOURCE_DIR` | `.cache/ontology_jsons` | Default directory containing OLS4 ontology JSON files |
94
+ | `ONTOLOGY_DB_PATH` | `.db/ontology_lookup.db` | Target SQLite database file path |
95
+ | `ONTOLOGY_BATCH_SIZE` | `5000` | SQLite batch insert transaction chunk size |
96
+ | `ONTOLOGY_PARENT_TERMS` | `MS:1000031,MS:1000076,MS:1000008,MS:1003761,...` | Comma-separated target parent CURIEs precomputed for transitive closure lookups |
97
+
98
+ > **Precedence Order**: Command-line flags (e.g. `--db`, `--dir`) override process environment variables, which override values in `.env`.
99
+
100
+ ### 3. Development & Quality Checks
101
+
102
+ Run Ruff linter, formatting checks, and pre-commit hooks:
103
+
104
+ ```bash
105
+ # Run Ruff linting
106
+ uv run ruff check .
107
+
108
+ # Automatically apply safe fixes
109
+ uv run ruff check --fix .
110
+
111
+ # Check formatting
112
+ uv run ruff format --check .
113
+
114
+ # Format code
115
+ uv run ruff format .
116
+
117
+ # Install pre-commit hooks
118
+ uv run pre-commit install
119
+ ```
120
+
121
+ ### 4. Running Tests
122
+
123
+ Run the full test suite across the loader, database manager, query service, and REST API:
124
+
125
+ ```bash
126
+ # Run all unit and integration tests
127
+ uv run pytest -v
128
+
129
+ # Run tests with short summary output
130
+ uv run pytest -q
131
+ ```
132
+
133
+ ---
134
+
135
+ ## Architecture and Design
136
+
137
+ ```
138
+ +---------------------------------------+
139
+ | OLS4 Compressed Source Dumps |
140
+ | (https://ftp.ebi.ac.uk/.../*.tgz) |
141
+ +-------------------+-------------------+
142
+ |
143
+ v (download & unpack)
144
+ +---------------------------------------+
145
+ | Local Cache: .cache/ontology_jsons/ |
146
+ | ms.json, edam.json, obi.json ... |
147
+ +-------------------+-------------------+
148
+ |
149
+ v
150
+ +---------------------------------------+
151
+ | Streaming Ingestion (ijson) |
152
+ | - Memory-bounded JSON streaming |
153
+ | - Transitive closure precomputation |
154
+ | - Leaf node detection (is_leaf tag) |
155
+ | - Metadata tag normalization |
156
+ +-------------------+-------------------+
157
+ |
158
+ v (Batch Ingest + WAL)
159
+ +-------------------------------------------------------+
160
+ | Optimized SQLite Database |
161
+ | +-------------------------------------------------+ |
162
+ | | terms: (curie, ontology PK, iri, label) | |
163
+ | | term_details (WITHOUT ROWID): | |
164
+ | | (curie, ontology, tag_key, tag_value PK) | |
165
+ | | terms_fts (FTS5 unicode61 porter): | |
166
+ | | (curie UNINDEXED, ontology UNINDEXED, ...) | |
167
+ | | ontologies: (ontology PK, name, prefix, counts) | |
168
+ | | database_info: (created_time, updated_time) | |
169
+ | +-------------------------------------------------+ |
170
+ +---------------------------+---------------------------+
171
+ |
172
+ +-----------------------+-----------------------+
173
+ | |
174
+ v (Direct / Embedded) v (Network / HTTP)
175
+ +-------------------------------+ +-------------------------------+
176
+ | OntologyLookupService | | FastAPI Web Service |
177
+ | - Reusable context manager | | - URI `mode=ro` concurrency |
178
+ | - B-Tree index scans (NOCASE)| | - 2 GB mmap_size |
179
+ | - Precomputed child-of tags | | - Sub-millisecond endpoints |
180
+ +-------------------------------+ +-------------------------------+
181
+ ```
182
+
183
+ ### Key Architectural Decisions
184
+
185
+ 1. **Streaming Multi-Gigabyte Ingestion (`ijson`)**:
186
+ OLS4 ontology files (e.g., `chebi.json`, `ncbitaxon.json`, `pr.json`) range from several hundred megabytes to multiple gigabytes. The ingestion pipeline streams class nodes via `ijson.items` to maintain a constant, low-memory footprint regardless of file size.
187
+
188
+ 2. **Cross-Ontology Referencing & Composite Primary Key (`curie, ontology`)**:
189
+ Ontologies frequently reference or import terms defined in other ontologies (for instance, `ms.json` references `OBI:0200114` and `UO:0000001` which are also defined in `obi.json` and `uo.json`). In the `terms` table, the composite primary key `(curie, ontology)` guarantees that every term is uniquely tracked within each referencing ontology, preserving ontology-specific labels, definitions, and relationships without collision. `term_details` similarly links via `FOREIGN KEY (curie, ontology) REFERENCES terms(curie, ontology) ON DELETE CASCADE`.
190
+
191
+ 3. **Index-Organized Metadata (`WITHOUT ROWID`)**:
192
+ Metadata tags (`synonym`, `child-of`, `obsolete`, `is_leaf`, `definition`) are stored in `term_details` with a composite primary key `(curie, ontology, tag_key, tag_value)`. Eliminating the standard 64-bit SQLite integer rowid cuts index overhead in half and clusters related tags contiguously on disk for blazing-fast sequential page reads.
193
+
194
+ 4. **Case-Insensitive Zero-Cost Matching (`COLLATE NOCASE`)**:
195
+ All identifier and text columns use SQLite's native `COLLATE NOCASE`. Queries match mixed-cased CURIEs (e.g. `ms:1000031` vs `MS:1000031`) or labels via instant B-Tree index lookups without calling `LOWER()` at runtime.
196
+
197
+ 5. **Full-Text Autocomplete & Relevance Search (`FTS5`)**:
198
+ SQLite's FTS5 engine (`unicode61` tokenizer with Porter stemming) indexes term labels, synonyms, and definitions with unindexed `ontology` scoping. It enables prefix matching, ranking, and tokenization without requiring external search daemons (e.g. Elasticsearch).
199
+
200
+ 6. **Infinite Read Concurrency (WAL + URI `mode=ro` + `mmap`)**:
201
+ - Write-Ahead Logging (`PRAGMA journal_mode = WAL;`) allows readers and writers to operate concurrently without locking.
202
+ - Read-only connections (`file:db.sqlite?mode=ro`) bypass write-lock coordination.
203
+ - `PRAGMA mmap_size = 2147483648;` memory-maps up to 2GB of the database directly into the OS page cache for sub-millisecond retrieval.
204
+ - FastAPI executes synchronous query endpoints in worker thread pools to handle hundreds of concurrent requests efficiently.
205
+
206
+ ---
207
+
208
+ ## Download ontology sources from OLS4
209
+
210
+ The EMBL-EBI Ontology Lookup Service (OLS4) distributes standardized JSON representations of all hosted ontologies.
211
+
212
+ - **Direct Download URL**: [https://ftp.ebi.ac.uk/pub/databases/spot/ols/latest/ontology_jsons.tgz](https://ftp.ebi.ac.uk/pub/databases/spot/ols/latest/ontology_jsons.tgz)
213
+ - **Default Local Location**: `.cache/ontology_jsons`
214
+
215
+ ### 1. Download and Extract the Archive
216
+
217
+ Execute the following commands to download and unpack the ontology JSON files into the `.cache` directory:
218
+
219
+ ```bash
220
+ # 1. Create target download directory
221
+ mkdir -p .cache
222
+
223
+ # 2. Download the compressed archive
224
+ curl -L https://ftp.ebi.ac.uk/pub/databases/spot/ols/latest/ontology_jsons.tgz -o .cache/ontology_jsons.tgz
225
+
226
+ # 3. Extract the archive into .cache/
227
+ tar -xzf .cache/ontology_jsons.tgz -C .cache/
228
+ ```
229
+
230
+ After extraction, the `.cache/ontology_jsons/` directory will contain individual JSON files named by ontology short name:
231
+
232
+ ```text
233
+ .cache/ontology_jsons/
234
+ ├── ms.json (Mass Spectrometry Controlled Vocabulary)
235
+ ├── edam.json (EDAM Bioinformatics operations, data, formats)
236
+ ├── obi.json (Ontology for Biomedical Investigations)
237
+ ├── bto.json (BRENDA Tissue Ontology)
238
+ ├── cl.json (Cell Ontology)
239
+ ├── clo.json (Cell Line Ontology)
240
+ ├── chmo.json (Chemical Methods Ontology)
241
+ ├── go.json (Gene Ontology)
242
+ └── ... (over 350+ ontologies)
243
+ ```
244
+
245
+ ### 2. Verify Available Ontologies
246
+
247
+ Use the CLI to inspect available JSON sources in `.cache/ontology_jsons`:
248
+
249
+ ```bash
250
+ uv run ontology-lookup list-ontologies --available --dir .cache/ontology_jsons
251
+ ```
252
+
253
+ ---
254
+
255
+ ## Build Multi-ontology Lookup Database
256
+
257
+ The lookup engine provides both **Command-Line Interface (CLI)** and **Python Library API** for creating databases, adding ontologies, deleting ontologies, and managing custom term tags.
258
+
259
+ ### CLI: Build and Database Management
260
+
261
+ All CLI operations are invoked via `uv run ontology-lookup` (or `ontology-lookup` if installed in your environment).
262
+
263
+ #### 1. Create Database (CLI)
264
+
265
+ Initialize a new multi-ontology SQLite database from JSON files in the source directory.
266
+
267
+ ```bash
268
+ # Build database with core proteomics and biological ontologies:
269
+ uv run ontology-lookup admin init-db \
270
+ --dir .cache/ontology_jsons \
271
+ --ontologies ms,edam,obi,msio \
272
+ --db .db/ontology_lookup.db \
273
+ --clean
274
+ ```
275
+
276
+ Parameters:
277
+
278
+ - `--dir`, `-i`: Directory containing ontology JSON files (default: `.cache/ontology_jsons`).
279
+ - `--ontologies`, `-o`: Comma-separated list of short names to ingest (e.g. `ms,edam,obi`). If omitted, all `*.json` files found in the directory are loaded.
280
+ - `--db`, `-d`: Target SQLite database path (default: `.db/ontology_lookup.db`).
281
+ - `--parents`, `-p`: Comma-separated target parent CURIEs for precomputing recursive `child-of` links.
282
+ - `--clean`: Recreates the database from scratch, removing any existing file.
283
+ - `--batch-size`, `-b`: Insert chunk size (default: `5000`).
284
+
285
+ Alternatively, build a database from a single standalone JSON file:
286
+
287
+ ```bash
288
+ uv run ontology-lookup admin build \
289
+ --source .cache/ontology_jsons/ms.json \
290
+ --ontology ms \
291
+ --db .db/ontology_lookup.db \
292
+ --clean
293
+ ```
294
+
295
+ #### 2. Add Ontologies (CLI)
296
+
297
+ Add or refresh an individual ontology in an existing database without modifying other ontologies:
298
+
299
+ ```bash
300
+ # Add or update 'bto' (BRENDA Tissue Ontology) from source directory:
301
+ uv run ontology-lookup admin update-ontology \
302
+ --name bto \
303
+ --dir .cache/ontology_jsons \
304
+ --db .db/ontology_lookup.db
305
+ ```
306
+
307
+ Or provide an explicit JSON file path:
308
+
309
+ ```bash
310
+ uv run ontology-lookup admin update-ontology \
311
+ --name cl \
312
+ --source /path/to/custom_cl.json \
313
+ --db .db/ontology_lookup.db
314
+ ```
315
+
316
+ #### 3. Delete Ontologies (CLI)
317
+
318
+ Completely delete an ontology, its terms, hierarchy links, tags, and full-text search entries:
319
+
320
+ ```bash
321
+ # Delete 'obi' from the database:
322
+ uv run ontology-lookup admin delete-ontology \
323
+ --name obi \
324
+ --db .db/ontology_lookup.db
325
+ ```
326
+
327
+ #### 4. Add/Update/Delete Term Tags (CLI)
328
+
329
+ Tags allow associating arbitrary key-value metadata (e.g. curation flags, custom categories, sub-classifications) with specific terms. An optional `--ontology / -o` flag allows scoping the tag to a specific ontology representation of the term.
330
+
331
+ ```bash
332
+ # Add a custom tag to a term (optionally scoped with -o ms):
333
+ uv run ontology-lookup admin add-tag \
334
+ --curie MS:1000031 \
335
+ --key custom_category \
336
+ --value instrumentation \
337
+ --ontology ms \
338
+ --db .db/ontology_lookup.db
339
+
340
+ # Update an existing tag value:
341
+ uv run ontology-lookup admin update-tag \
342
+ --curie MS:1000031 \
343
+ --key custom_category \
344
+ --value core_hardware \
345
+ --old-value instrumentation \
346
+ --ontology ms \
347
+ --db .db/ontology_lookup.db
348
+
349
+ # Delete a specific tag value:
350
+ uv run ontology-lookup admin delete-tag \
351
+ --curie MS:1000031 \
352
+ --key custom_category \
353
+ --value core_hardware \
354
+ --ontology ms \
355
+ --db .db/ontology_lookup.db
356
+
357
+ # Delete all tags matching a key for a term:
358
+ uv run ontology-lookup admin delete-tag \
359
+ --curie MS:1000031 \
360
+ --key custom_category \
361
+ --db .db/ontology_lookup.db
362
+ ```
363
+
364
+ #### 5. Inspect Database and Ontologies (CLI)
365
+
366
+ ```bash
367
+ # List all installed ontologies, term counts, versions, and IRI prefixes:
368
+ uv run ontology-lookup list-ontologies --db .db/ontology_lookup.db
369
+
370
+ # View database creation and last-updated metadata:
371
+ uv run ontology-lookup database-info --db .db/ontology_lookup.db
372
+ ```
373
+
374
+ ---
375
+
376
+ ### Python API: Build and Database Management
377
+
378
+ The `OntologyDatabaseManager` ([src/ontology_lookup/manager.py](src/ontology_lookup/manager.py)) class provides programmatic control over database lifecycle operations.
379
+
380
+ #### 1. Create Database (API)
381
+
382
+ ```python
383
+ from ontology_lookup.manager import OntologyDatabaseManager, create_database
384
+
385
+ # Option A: Using the OntologyDatabaseManager class
386
+ mgr = OntologyDatabaseManager(
387
+ db_path=".db/ontology_lookup.db",
388
+ default_input_dir=".cache/ontology_jsons",
389
+ batch_size=5000,
390
+ )
391
+
392
+ # Load selected ontologies (or pass ontologies=None to load all available JSONs)
393
+ results = mgr.create_database(
394
+ source_dir=".cache/ontology_jsons",
395
+ ontologies=["ms", "edam", "obi"],
396
+ clean=True,
397
+ )
398
+ print("Ingestion results:", results)
399
+ # Output: {'ms': {'terms': 3542, 'details': 15230}, 'edam': {'terms': 3820, 'details': 12400}, ...}
400
+
401
+ # Option B: Using the module-level helper function
402
+ results = create_database(
403
+ db_path=".db/ontology_lookup.db",
404
+ source_dir=".cache/ontology_jsons",
405
+ ontologies=["ms", "edam"],
406
+ clean=True,
407
+ )
408
+ ```
409
+
410
+ #### 2. Add Ontologies (API)
411
+
412
+ **Python API**:
413
+
414
+ ```python
415
+ from ontology_lookup.manager import OntologyDatabaseManager
416
+
417
+ mgr = OntologyDatabaseManager(db_path=".db/ontology_lookup.db")
418
+
419
+ # Ingest or update 'chmo' from default source directory:
420
+ terms_count, details_count = mgr.update_ontology(
421
+ ontology_name="chmo",
422
+ source_dir=".cache/ontology_jsons",
423
+ )
424
+ print(f"Added CHMO: {terms_count} terms, {details_count} details.")
425
+
426
+ # Ingest from an explicit file path:
427
+ terms, details = mgr.load_file(
428
+ file_path=".cache/ontology_jsons/bto.json",
429
+ ontology_name="bto",
430
+ )
431
+ ```
432
+
433
+ **REST API**:
434
+
435
+ ```bash
436
+ # Add or refresh 'chmo' from default source directory
437
+ curl -X POST "http://localhost:8000/ontologies/chmo"
438
+
439
+ # Add or update from specific source directory
440
+ curl -X PUT "http://localhost:8000/ontologies/bto?source_dir=.cache/ontology_jsons"
441
+ ```
442
+
443
+ #### 3. Delete Ontologies (API)
444
+
445
+ **Python API**:
446
+
447
+ ```python
448
+ from ontology_lookup.manager import OntologyDatabaseManager
449
+
450
+ mgr = OntologyDatabaseManager(db_path=".db/ontology_lookup.db")
451
+
452
+ # Completely remove an ontology and all its associated terms, details, and FTS entries:
453
+ removed_terms = mgr.delete_ontology("obi")
454
+ print(f"Removed {removed_terms} terms from the database.")
455
+ ```
456
+
457
+ **REST API**:
458
+
459
+ ```bash
460
+ # Delete ontology 'obi' and all its terms/details
461
+ curl -X DELETE "http://localhost:8000/ontologies/obi"
462
+ ```
463
+
464
+ #### 4. Add/Update/Delete Term Tags (API)
465
+
466
+ **Python API**:
467
+
468
+ ```python
469
+ from ontology_lookup.manager import OntologyDatabaseManager
470
+
471
+ mgr = OntologyDatabaseManager(db_path=".db/ontology_lookup.db")
472
+
473
+ # 1. Add custom tag to term (optionally scoped to a specific ontology)
474
+ success = mgr.add_term_tag(
475
+ curie="MS:1000031",
476
+ tag_key="curation_status",
477
+ tag_value="verified",
478
+ ontology="ms",
479
+ )
480
+
481
+ # 2. Update tag value
482
+ mgr.update_term_tag(
483
+ curie="MS:1000031",
484
+ tag_key="curation_status",
485
+ new_value="approved",
486
+ old_value="verified",
487
+ ontology="ms",
488
+ )
489
+
490
+ # 3. Delete tag
491
+ mgr.delete_term_tag(
492
+ curie="MS:1000031",
493
+ tag_key="curation_status",
494
+ tag_value="approved",
495
+ ontology="ms",
496
+ )
497
+ ```
498
+
499
+ **REST API**:
500
+
501
+ ```bash
502
+ # 1. Add tag to term (accepts optional ?ontology=ms query parameter)
503
+ curl -X POST "http://localhost:8000/terms/MS:1000031/tags?ontology=ms" \
504
+ -H "Content-Type: application/json" \
505
+ -d '{"tag_key": "curation_status", "tag_value": "verified"}'
506
+
507
+ # 2. Update existing tag value
508
+ curl -X PUT "http://localhost:8000/terms/MS:1000031/tags/curation_status?ontology=ms" \
509
+ -H "Content-Type: application/json" \
510
+ -d '{"tag_value": "approved", "old_value": "verified"}'
511
+
512
+ # 3. Delete specific tag value
513
+ curl -X DELETE "http://localhost:8000/terms/MS:1000031/tags/curation_status?tag_value=approved&ontology=ms"
514
+
515
+ # 4. Delete all tags matching tag_key for the term
516
+ curl -X DELETE "http://localhost:8000/terms/MS:1000031/tags/curation_status"
517
+ ```
518
+
519
+ #### 5. Inspect Database and Ontologies (API)
520
+
521
+ **Python API**:
522
+
523
+ ```python
524
+ from ontology_lookup.manager import OntologyDatabaseManager
525
+
526
+ mgr = OntologyDatabaseManager(db_path=".db/ontology_lookup.db")
527
+
528
+ # List installed ontologies and summary counts
529
+ installed = mgr.list_installed_ontologies()
530
+ for ont in installed:
531
+ print(f"{ont['ontology']} (v{ont['version']}): {ont['num_of_terms']} terms")
532
+
533
+ # Inspect database timestamp info
534
+ info = mgr.get_database_info()
535
+ print(f"Created: {info['created_time']}, Updated: {info['updated_time']}")
536
+ ```
537
+
538
+ **REST API**:
539
+
540
+ ```bash
541
+ # List all installed ontologies
542
+ curl -X GET "http://localhost:8000/ontologies"
543
+
544
+ # Get metadata for a specific ontology
545
+ curl -X GET "http://localhost:8000/ontologies/ms"
546
+
547
+ # Inspect database metadata
548
+ curl -X GET "http://localhost:8000/info"
549
+ ```
550
+
551
+ ---
552
+
553
+ ## Search on Multi-ontology Lookup Database
554
+
555
+ The query layer supports **8 primary use cases** available via both the **CLI** and **API** (Python service + REST HTTP endpoints).
556
+ The `search` and `freetext-search` use cases accept multiple ontology filters: pass comma-separated names in the CLI, a list in Python, or repeat the `ontology` query parameter in HTTP requests.
557
+
558
+ ### Starting the REST API Server
559
+
560
+ To enable HTTP access to your database, start the FastAPI server:
561
+
562
+ ```bash
563
+ uv run ontology-lookup serve --db .db/ontology_lookup.db --host 0.0.0.0 --port 8000
564
+ ```
565
+
566
+ Interactive OpenAPI documentation and Swagger UI will be available at:
567
+
568
+ - **Swagger UI**: `http://localhost:8000/docs`
569
+ - **ReDoc UI**: `http://localhost:8000/redoc`
570
+
571
+ ### API Endpoints Reference Table
572
+
573
+ | Endpoint | HTTP Method | Query / Path / Body Parameters | Description |
574
+ | --- | --- | --- | --- |
575
+ | `/terms/{accession}` | `GET` | `accession` (path), `ontology` (opt) | Lookup term by CURIE or full IRI (case-insensitive) |
576
+ | `/terms/{accession}/tags` | `POST` | `accession` (path), body `{"tag_key", "tag_value"}` | Add a key-value tag to a term |
577
+ | `/terms/{accession}/tags/{tag_key}` | `PUT` | `accession` (path), `tag_key` (path), body `{"tag_value", "old_value"}` | Update a tag value for a term |
578
+ | `/terms/{accession}/tags/{tag_key}` | `DELETE` | `accession` (path), `tag_key` (path), `tag_value` (opt query) | Delete one or all tags matching key for a term |
579
+ | `/ontologies/{ontology}/terms/{accession}` | `GET` | `ontology` (path), `accession` (path) | Scoped lookup within explicit ontology |
580
+ | `/search/exact` | `GET` | `ontology`, `label` | Exact match lookup on term label |
581
+ | `/search` | `GET` | `q`, `search_in_synonyms`, repeatable `ontology` and `parent_curie`, `limit`, `offset` | Case-insensitive exact match on labels or synonyms |
582
+ | `/search/freetext` | `GET` | `q`, repeatable `ontology` and `parent_curie`, `limit`, `offset` | Ranked freetext search across labels, synonyms, and definitions |
583
+ | `/search/tags` | `GET` | `tag_key`, `tag_value`, `ontology` (opt), `limit`, `offset` | Search terms by metadata tags (e.g. `is_leaf`, `obsolete`) |
584
+ | `/resolve/curie` | `GET` | `iri`, `ontology` (opt) | Resolve a full IRI back to its primary CURIE |
585
+ | `/resolve/iri` | `GET` | `curie`, `ontology` (opt) | Resolve a CURIE to its IRI |
586
+ | `/children/{parent_curie}` | `GET` | `parent_curie` (path), `ontology` (opt), `limit`, `offset` | Get all recursive descendants of a parent CURIE |
587
+ | `/parent-terms` | `GET` | *None* | List parent CURIEs referenced by indexed `child-of` tags |
588
+ | `/ontologies` | `GET` | *None* | List installed ontologies with version, terms, obsoletes, and details |
589
+ | `/ontologies/{ontology}` | `GET` | `ontology` (path) | Get metadata for a specific installed ontology |
590
+ | `/ontologies/{ontology}` | `POST` / `PUT` | `ontology` (path), `source_dir` (opt), `source_file` (opt) | Add or update an ontology from source JSON |
591
+ | `/ontologies/{ontology}` | `DELETE` | `ontology` (path) | Delete an ontology, its terms, hierarchy links, and FTS entries |
592
+ | `/info` | `GET` | *None* | Retrieve database creation and last-updated metadata |
593
+ | `/health` | `GET` | *None* | Service health status and total terms count |
594
+
595
+ ---
596
+
597
+ ### Use Case 1: Term Lookup by CURIE or IRI (Accession)
598
+
599
+ Fetch the complete record for a term, including aggregated synonyms, hierarchy links (`children_of`), and metadata tags. Case-insensitive.
600
+
601
+ > [!NOTE]
602
+ > **Cross-Ontology Term Referencing**: When a term is referenced or imported by multiple ontologies (e.g. `OBI:0200114` is referenced in `ms` and defined in `obi`), specify `--ontology` to fetch the exact representation for that ontology.
603
+
604
+ #### CLI Examples
605
+
606
+ ```bash
607
+ # Example 1: Lookup by CURIE
608
+ uv run ontology-lookup get-term-by-accession --ontology ms --accession MS:1000031 --db .db/ontology_lookup.db
609
+
610
+ # Example 2: Lookup by lowercase CURIE (case-insensitive)
611
+ uv run ontology-lookup get-term-by-accession --ontology ms --accession ms:1000449 --db .db/ontology_lookup.db
612
+
613
+ # Example 3: Lookup cross-referenced term in distinct ontologies
614
+ uv run ontology-lookup get-term-by-accession --ontology ms --accession OBI:0200114 --db .db/ontology_lookup.db
615
+ uv run ontology-lookup get-term-by-accession --ontology obi --accession OBI:0200114 --db .db/ontology_lookup.db
616
+ ```
617
+
618
+ #### API Examples
619
+
620
+ ```python
621
+ from ontology_lookup.service import OntologyLookupService
622
+
623
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
624
+ # Example 1: Lookup by CURIE
625
+ term1 = svc.get_term_by_accession(ontology="ms", accession="MS:1000031")
626
+ print(term1.label, term1.synonyms, term1.children_of)
627
+
628
+ # Example 2: Lookup by lowercase CURIE
629
+ term2 = svc.get_term_by_accession(ontology="ms", accession="ms:1000449")
630
+ print(term2.curie, term2.label)
631
+
632
+ # Example 3: Cross-referenced term lookup across ontologies
633
+ term_ms = svc.get_term_by_accession(ontology="ms", accession="OBI:0200114")
634
+ term_obi = svc.get_term_by_accession(ontology="obi", accession="OBI:0200114")
635
+ print(f"MS: {term_ms.curie} -> {term_ms.label}")
636
+ print(f"OBI: {term_obi.curie} -> {term_obi.label} (tags: {list(term_obi.tags.keys())})")
637
+ ```
638
+
639
+ **REST API (HTTP)**:
640
+
641
+ ```bash
642
+ # Example 1: Lookup by CURIE
643
+ curl -X GET "http://localhost:8000/terms/MS:1000031"
644
+
645
+ # Example 2: Lookup by lowercase CURIE with explicit ontology
646
+ curl -X GET "http://localhost:8000/ontologies/ms/terms/ms:1000449"
647
+
648
+ # Example 3: Cross-referenced term lookup in distinct ontologies
649
+ curl -X GET "http://localhost:8000/ontologies/ms/terms/OBI:0200114"
650
+ curl -X GET "http://localhost:8000/ontologies/obi/terms/OBI:0200114"
651
+ ```
652
+
653
+ ---
654
+
655
+ ### Use Case 2: Exact Label Match
656
+
657
+ Look up a term by exact label within an ontology (case-insensitive).
658
+
659
+ #### CLI Examples
660
+
661
+ ```bash
662
+ # Example 1: Exact instrument label (matches MS:1000031)
663
+ uv run ontology-lookup get-term-by-label --ontology ms --label "instrument model" --db .db/ontology_lookup.db
664
+
665
+ # Example 2: Case-insensitive label query (matches MS:1000449)
666
+ uv run ontology-lookup get-term-by-label --ontology ms --label "LTQ ORBITRAP" --db .db/ontology_lookup.db
667
+
668
+ # Example 3: Exact match in another ontology (matches OBI:0000070)
669
+ uv run ontology-lookup get-term-by-label --ontology obi --label "assay" --db .db/ontology_lookup.db
670
+ ```
671
+
672
+ #### API Examples
673
+
674
+ ```python
675
+ from ontology_lookup.service import OntologyLookupService
676
+
677
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
678
+ # Example 1: Exact label
679
+ term1 = svc.get_term_by_exact_label(ontology="ms", label="instrument model")
680
+ print(term1.curie, term1.label)
681
+
682
+ # Example 2: Case-insensitive label
683
+ term2 = svc.get_term_by_exact_label(ontology="ms", label="LTQ ORBITRAP")
684
+ print(term2.curie, term2.label)
685
+
686
+ # Example 3: Match in OBI
687
+ term3 = svc.get_term_by_exact_label(ontology="obi", label="assay")
688
+ print(term3.curie if term3 else "Not found")
689
+ ```
690
+
691
+ **REST API (HTTP)**:
692
+
693
+ ```bash
694
+ # Example 1: Exact label
695
+ curl -X GET "http://localhost:8000/search/exact?ontology=ms&label=instrument+model"
696
+
697
+ # Example 2: Case-insensitive uppercase label
698
+ curl -X GET "http://localhost:8000/search/exact?ontology=ms&label=LTQ+ORBITRAP"
699
+
700
+ # Example 3: Biological assay in OBI
701
+ curl -X GET "http://localhost:8000/search/exact?ontology=obi&label=assay"
702
+ ```
703
+
704
+ ---
705
+
706
+ ### Use Case 3: Exact Match Search across Labels and Synonyms
707
+
708
+ Case-insensitive exact matching against complete labels and synonyms. Partial matches and definitions are excluded. Use `freetext-search` (Use Case 8) for ranked keyword and definition search. Optional ontology and parent CURIE filters can narrow the results.
709
+
710
+ #### CLI Examples
711
+
712
+ ```bash
713
+ # Example 1: Match a complete label
714
+ uv run ontology-lookup search-by-label --label-or-synonym "orbitrap" -o ms --db .db/ontology_lookup.db
715
+
716
+ # Example 2: Query by synonym (e.g. 'MALDI' matches MS:1000031)
717
+ uv run ontology-lookup search-by-label --label-or-synonym "MALDI" -o ms --db .db/ontology_lookup.db
718
+
719
+ # Example 3: Exact label or synonym across multiple ontologies
720
+ uv run ontology-lookup search-by-label --label-or-synonym "instrument" -o ms,edam -l 10 --db .db/ontology_lookup.db
721
+ ```
722
+
723
+ #### API Examples
724
+
725
+ ```python
726
+ from ontology_lookup.service import OntologyLookupService
727
+
728
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
729
+ # Example 1: Search label
730
+ results1 = svc.search_by_label(label_or_synonym="orbitrap", ontology="ms", limit=5)
731
+ for r in results1:
732
+ print(f"[{r.curie}] {r.label}")
733
+
734
+ # Example 2: Search synonym
735
+ results2 = svc.search_by_label(label_or_synonym="MALDI", ontology="ms")
736
+ for r in results2:
737
+ print(f"[{r.curie}] {r.label}")
738
+
739
+ # Example 3: Exact match across multiple ontologies
740
+ results3 = svc.search_by_label(label_or_synonym="instrument", ontology=["ms", "edam"], limit=10)
741
+ print(f"Found {len(results3)} results")
742
+ ```
743
+
744
+ **REST API (HTTP)**:
745
+
746
+ ```bash
747
+ # Example 1: Query label
748
+ curl -X GET "http://localhost:8000/search?q=orbitrap&ontology=ms"
749
+
750
+ # Example 2: Query synonym
751
+ curl -X GET "http://localhost:8000/search?q=MALDI&ontology=ms"
752
+
753
+ # Example 3: Multi-ontology search with limit
754
+ curl -X GET "http://localhost:8000/search?q=instrument&ontology=ms&ontology=edam&limit=10"
755
+ ```
756
+
757
+ ---
758
+
759
+ ### Use Case 4: Hierarchy-Constrained Search (Parent CURIE Filter)
760
+
761
+ Restrict exact label or synonym matches to descendants of specific parent terms using indexed hierarchy tags.
762
+
763
+ #### CLI Examples
764
+
765
+ ```bash
766
+ # Example 1: Search only descendants of 'instrument model' (MS:1000031)
767
+ uv run ontology-lookup search-by-label --label-or-synonym "LTQ Orbitrap" -o ms -p MS:1000031 --db .db/ontology_lookup.db
768
+
769
+ # Example 2: Search within 'ionization type' (MS:1000008)
770
+ uv run ontology-lookup search-by-label --label-or-synonym "electrospray ionization" -o ms -p MS:1000008 --db .db/ontology_lookup.db
771
+
772
+ # Example 3: Filter across multiple parent CURIEs
773
+ uv run ontology-lookup search-by-label --label-or-synonym "MALDI" -o ms -p MS:1000031,MS:1000008 --db .db/ontology_lookup.db
774
+ ```
775
+
776
+ #### API Examples
777
+
778
+ ```python
779
+ from ontology_lookup.service import OntologyLookupService
780
+
781
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
782
+ # Example 1: Restrict search to instrument models
783
+ res1 = svc.search_by_label(
784
+ label_or_synonym="LTQ Orbitrap", ontology="ms", parent_curie="MS:1000031"
785
+ )
786
+ print(f"Found {len(res1)} matches under MS:1000031")
787
+
788
+ # Example 2: Search within ionization type hierarchy
789
+ res2 = svc.search_by_label(
790
+ label_or_synonym="electrospray ionization", ontology="ms", parent_curie="MS:1000008"
791
+ )
792
+ for r in res2:
793
+ print(r.curie, r.label)
794
+
795
+ # Example 3: Filter across multiple parent CURIEs
796
+ res3 = svc.search_by_label(
797
+ label_or_synonym="MALDI",
798
+ ontology=["ms"],
799
+ parent_curie=["MS:1000031", "MS:1000008"],
800
+ )
801
+ print(f"Multi-parent matches: {len(res3)}")
802
+ ```
803
+
804
+ **REST API (HTTP)**:
805
+
806
+ ```bash
807
+ # Example 1: Parent filter under instrument model
808
+ curl -X GET "http://localhost:8000/search?q=LTQ+Orbitrap&ontology=ms&parent_curie=MS:1000031"
809
+
810
+ # Example 2: Hierarchy filter under ionization type
811
+ curl -X GET "http://localhost:8000/search?q=electrospray+ionization&ontology=ms&parent_curie=MS:1000008"
812
+
813
+ # Example 3: Multiple parent CURIE filters
814
+ curl -X GET "http://localhost:8000/search?q=MALDI&ontology=ms&parent_curie=MS:1000031&parent_curie=MS:1000008"
815
+ ```
816
+
817
+ ---
818
+
819
+ ### List Indexed Parent Terms
820
+
821
+ List the distinct parent CURIEs referenced by indexed `child-of` hierarchy tags:
822
+
823
+ ```bash
824
+ uv run ontology-lookup list-parent-terms --db .db/ontology_lookup.db
825
+ ```
826
+
827
+ The same use case is available from the Python service and REST API:
828
+
829
+ ```python
830
+ from ontology_lookup.service import OntologyLookupService
831
+
832
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
833
+ for parent_curie in svc.get_indexed_parent_terms():
834
+ print(parent_curie)
835
+ ```
836
+
837
+ ```bash
838
+ curl -X GET "http://localhost:8000/parent-terms"
839
+ ```
840
+
841
+ ---
842
+
843
+ ### Use Case 5: CURIE and IRI Resolution
844
+
845
+ Map bidirectional relationships between persistent IRIs and compact CURIE accessions.
846
+
847
+ #### CLI Examples
848
+
849
+ ```bash
850
+ # Example 1: Resolve full IRI to CURIE
851
+ uv run ontology-lookup iri-to-curie --iri "http://purl.obolibrary.org/obo/MS_1000031" --ontology ms --db .db/ontology_lookup.db
852
+
853
+ # Example 2: Resolve CURIE to IRI
854
+ uv run ontology-lookup curie-to-iri --curie "MS:1000031" --ontology ms --db .db/ontology_lookup.db
855
+
856
+ # Example 3: Resolve IRI across entire database (unscoped)
857
+ uv run ontology-lookup iri-to-curie --iri "http://edamontology.org/format_1915" --db .db/ontology_lookup.db
858
+ ```
859
+
860
+ #### API Examples
861
+
862
+ ```python
863
+ from ontology_lookup.service import OntologyLookupService
864
+
865
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
866
+ # Example 1: IRI to CURIE
867
+ res1 = svc.find_curie(iri="http://purl.obolibrary.org/obo/MS_1000031", ontology="ms")
868
+ print(f"CURIE: {res1.curie if res1 else 'Not found'}")
869
+
870
+ # Example 2: CURIE to IRI
871
+ res2 = svc.find_iri(curie="MS:1000031", ontology="ms")
872
+ print(f"IRI: {res2.iri if res2 else 'Not found'}")
873
+
874
+ # Example 3: Unscoped IRI resolution
875
+ res3 = svc.find_curie(iri="http://edamontology.org/format_1915")
876
+ print(f"Unscoped CURIE: {res3.curie if res3 else 'Not found'}")
877
+ ```
878
+
879
+ **REST API (HTTP)**:
880
+
881
+ ```bash
882
+ # Example 1: Resolve full IRI to CURIE
883
+ curl -X GET "http://localhost:8000/resolve/curie?iri=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FMS_1000031&ontology=ms"
884
+
885
+ # Example 2: Resolve CURIE to full IRI
886
+ curl -X GET "http://localhost:8000/resolve/iri?curie=MS:1000031&ontology=ms"
887
+
888
+ # Example 3: Resolve IRI across entire database (unscoped)
889
+ curl -X GET "http://localhost:8000/resolve/curie?iri=http%3A%2F%2Fedamontology.org%2Fformat_1915"
890
+ ```
891
+
892
+ ---
893
+
894
+ ### Use Case 6: Key-Value Metadata Tag Search
895
+
896
+ Query terms by normalized tags such as `is_leaf`, `obsolete`, or custom annotations.
897
+
898
+ #### CLI Examples
899
+
900
+ ```bash
901
+ # Example 1: Find obsolete terms in an ontology
902
+ uv run ontology-lookup search-by-tag --tag-key obsolete --tag-value true -o ms --db .db/ontology_lookup.db
903
+
904
+ # Example 2: Find leaf terms (terms without child terms)
905
+ uv run ontology-lookup search-by-tag --tag-key is_leaf --tag-value 1 -o ms -l 10 --db .db/ontology_lookup.db
906
+
907
+ # Example 3: Search terms by custom tag key and value
908
+ uv run ontology-lookup search-by-tag --tag-key custom_category --tag-value instrumentation --db .db/ontology_lookup.db
909
+ ```
910
+
911
+ #### API Examples
912
+
913
+ ```python
914
+ from ontology_lookup.service import OntologyLookupService
915
+
916
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
917
+ # Example 1: Search obsolete terms
918
+ obsoletes = svc.search_by_tag(tag_key="obsolete", tag_value="true", ontology="ms")
919
+ print(f"Found {len(obsoletes)} obsolete terms in MS")
920
+
921
+ # Example 2: Search leaf terms
922
+ leaves = svc.search_by_tag(tag_key="is_leaf", tag_value="1", ontology="ms", limit=5)
923
+ for leaf in leaves:
924
+ print(f"Leaf term: {leaf.curie} - {leaf.label}")
925
+
926
+ # Example 3: Search by custom tag
927
+ custom_terms = svc.search_by_tag(tag_key="custom_category", tag_value="instrumentation")
928
+ print(f"Tagged terms count: {len(custom_terms)}")
929
+ ```
930
+
931
+ **REST API (HTTP)**:
932
+
933
+ ```bash
934
+ # Example 1: Find obsolete terms
935
+ curl -X GET "http://localhost:8000/search/tags?tag_key=obsolete&tag_value=true&ontology=ms"
936
+
937
+ # Example 2: Find leaf nodes
938
+ curl -X GET "http://localhost:8000/search/tags?tag_key=is_leaf&tag_value=1&ontology=ms&limit=10"
939
+
940
+ # Example 3: Query custom user metadata tags
941
+ curl -X GET "http://localhost:8000/search/tags?tag_key=custom_category&tag_value=instrumentation"
942
+ ```
943
+
944
+ ---
945
+
946
+ ### Use Case 7: Recursive Descendants / Children Lookup
947
+
948
+ Retrieve all terms that inherit from a specified parent CURIE.
949
+
950
+ #### CLI Examples
951
+
952
+ ```bash
953
+ # Example 1: Find descendants of instrument model (MS:1000031)
954
+ uv run ontology-lookup get-children --parent MS:1000031 -o ms --db .db/ontology_lookup.db
955
+
956
+ # Example 2: Find descendants of ionization type (MS:1000008)
957
+ uv run ontology-lookup get-children --parent MS:1000008 -o ms --db .db/ontology_lookup.db
958
+
959
+ # Example 3: Paginated descendants query with limit and offset
960
+ uv run ontology-lookup get-children --parent MS:1000031 -o ms --limit 5 --offset 0 --db .db/ontology_lookup.db
961
+ ```
962
+
963
+ #### API Examples
964
+
965
+ ```python
966
+ from ontology_lookup.service import OntologyLookupService
967
+
968
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
969
+ # Example 1: Children of instrument model
970
+ children1 = svc.get_children(parent_curie="MS:1000031", ontology="ms")
971
+ print(f"Children of MS:1000031: {len(children1)}")
972
+
973
+ # Example 2: Children of ionization type
974
+ children2 = svc.get_children(parent_curie="MS:1000008", ontology="ms")
975
+ for child in children2:
976
+ print(f" -> {child.curie}: {child.label}")
977
+
978
+ # Example 3: Paginated children lookup
979
+ children3 = svc.get_children(parent_curie="MS:1000031", ontology="ms", limit=5, offset=5)
980
+ print(f"Page 2 count: {len(children3)}")
981
+ ```
982
+
983
+ **REST API (HTTP)**:
984
+
985
+ ```bash
986
+ # Example 1: Recursive children of instrument model
987
+ curl -X GET "http://localhost:8000/children/MS:1000031?ontology=ms"
988
+
989
+ # Example 2: Recursive children of ionization type
990
+ curl -X GET "http://localhost:8000/children/MS:1000008?ontology=ms"
991
+
992
+ # Example 3: Paginated children
993
+ curl -X GET "http://localhost:8000/children/MS:1000031?ontology=ms&limit=5&offset=5"
994
+ ```
995
+
996
+ ---
997
+
998
+ ### Use Case 8: Freetext Search (Labels, Synonyms, and Definitions)
999
+
1000
+ Perform ranked search across term labels, synonyms, and detailed text definitions using SQLite FTS5 BM25-based ranking.
1001
+
1002
+ #### CLI Examples
1003
+
1004
+ ```bash
1005
+ # Example 1: Match definition text (e.g. manufacturer name)
1006
+ uv run ontology-lookup freetext-search -q "Thermo Scientific" -o ms --db .db/ontology_lookup.db
1007
+
1008
+ # Example 2: Search specific hybrid spectrometer types
1009
+ uv run ontology-lookup freetext-search -q "orbitrap mass spectrometer" -o ms -l 5 --db .db/ontology_lookup.db
1010
+
1011
+ # Example 3: Search multiple ontologies with a parent constraint
1012
+ uv run ontology-lookup freetext-search -q "quadrupole" -o ms,edam -p MS:1000031 --db .db/ontology_lookup.db
1013
+ ```
1014
+
1015
+ #### API Examples
1016
+
1017
+ ```python
1018
+ from ontology_lookup.service import OntologyLookupService
1019
+
1020
+ with OntologyLookupService(db_path=".db/ontology_lookup.db") as svc:
1021
+ # Example 1: Search definition text
1022
+ results1 = svc.freetext_search(query="Thermo Scientific", ontology="ms")
1023
+ for r in results1:
1024
+ print(f"[{r.curie}] {r.label} (Rank: {r.rank:.2f})")
1025
+
1026
+ # Example 2: Multi-keyword ranked search
1027
+ results2 = svc.freetext_search(query="orbitrap mass spectrometer", ontology=["ms"], limit=5)
1028
+ for r in results2:
1029
+ print(f"[{r.curie}] {r.label}")
1030
+
1031
+ # Example 3: Multi-ontology freetext search with parent filter
1032
+ results3 = svc.freetext_search(
1033
+ query="quadrupole",
1034
+ ontology=["ms", "edam"],
1035
+ parent_curie=["MS:1000031"],
1036
+ )
1037
+ print(f"Matches found: {len(results3)}")
1038
+ ```
1039
+
1040
+ **REST API (HTTP)**:
1041
+
1042
+ ```bash
1043
+ # Example 1: Search definition text
1044
+ curl -X GET "http://localhost:8000/search/freetext?q=Thermo+Scientific&ontology=ms"
1045
+
1046
+ # Example 2: Multi-keyword ranked search
1047
+ curl -X GET "http://localhost:8000/search/freetext?q=orbitrap+mass+spectrometer&ontology=ms&limit=5"
1048
+
1049
+ # Example 3: Multi-ontology freetext query with parent filter
1050
+ curl -X GET "http://localhost:8000/search/freetext?q=quadrupole&ontology=ms&ontology=edam&parent_curie=MS:1000031"
1051
+ ```