TopicDB: a Python topic map-based semantic graph library (using PostgreSQL for persistence)
Python Jupyter Notebook
Clone or download


TopicDB from StoryTechnologies

TopicDB is a topic map-based graph library (using PostgreSQL for persistence).

For a more in-depth introduction to topic maps, I recommend reading the excellent introductory article on topic maps over at MSDN: An Introduction to Topic Maps. With that being said, although TopicDB is inspired by the topic maps paradigm, it is not (and never will be) an implementation of the ISO/IEC 13250 Topic Maps data model standard.

TopicDB is intended to be used by other Python applications, and currently does not provide a web interface to the API. Story Engine is a good example of TopicDB being used by another application.


I build (story) worlds. TopicDB plays a crucial role in that endeavour.

Feature Support

  • Pending


TopicDB officially supports Python 3.3–3.6. To install TopicDB, simply:

$ pip install topic-db

First-Time Use

from import TopicStore
from import RetrievalOption

from topicdb.core.models.topic import Topic
from topicdb.core.models.language import Language


# Instantiate and open topic store.
with TopicStore('username', 'password') as store:

    # Create the topic map and bootstrap default topics.
    store.set_topic_map(TOPIC_MAP_IDENTIFIER, "Topic Map Test")

    topic1 = Topic(identifier='test-topic1',
                   base_name='Tópico de Prueba',

    # Persist topic to store.
    if not store.topic_exists(TOPIC_MAP_IDENTIFIER, 'test-topic1'):
        store.set_topic(TOPIC_MAP_IDENTIFIER, topic1)

    # Retrieve topic from store (with the accompanying topic attributes).
    topic2 = store.get_topic(TOPIC_MAP_IDENTIFIER, 'test-topic1',


To get a better understanding of how to use TopicDB, check out the tutorial, here: TopicDB Tutorial (work-in-progress).


Documentation will be available soon.

How to Contribute

  1. Fork the repository on GitHub to start making your changes to the master branch (or branch off of it).
  2. Write a test which shows that the bug was fixed or that the feature works as expected.
  3. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS.