Skip to content

Conversation

krishnangovindraj
Copy link
Member

Must do:

  • Update readme
  • Ensure build & install from source works.

What is the goal of this PR?

Updates the plugin for TypeDB 3.x. The simplified driver implementation & protocol has also allowed us to move to a different architecture. Major changes include:

Major new 'features'

  • A split into %typedb line magic for general administrative commands, and %%typeql cell magic for running queries
  • A utility library, intended to hold functions such as conversions to networkx, & interfaces such as visualisable graph builders.
  • Sample notebooks to serve as a quick-start - including one graph visualisation.

Subtle UX changes

  • We only support one implicit transaction at a time - no more aliases.
  • We implicitly store the result of the transaction in the _typeql_resultvariable (as well as returning it to the cell) - no magic parameter to specify the variable name. Just re-assign it in the next cell.

Missing features:

  • Various output formats such as JSON
  • Transaction & Query options

What are the changes implemented in this PR?

I've taken inspiration from the 2.x version, but also taken the freedom to move to a more opinionated architecture which resembles TypeDB console. Specifically:

  • The move towards resembling console commands, and the separation of %typedb and %%typeql magics.
  • The re-architecture into SubCommands reflecting each %typedb <sub-command>
    • The intent is organisation, as the console command syntax dictates where the code must be.
  • A hacky-parser that reconstructs a query structure on the client side, mainly for use with visualisation
    • Notably, an imminent TypeDB feature will make this redundant, as the query-structure will be returned in the response.

I'm not married to any of these and it should be straightforward to re-implement them if there's demand for it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please hit the '...' on the top-right and select 'view file' to see the rendered version.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please hit the '...' on the top-right and select 'view file' to see the rendered version.

@james-whiteside james-whiteside marked this pull request as ready for review May 25, 2025 16:30
@james-whiteside james-whiteside self-requested a review as a code owner May 25, 2025 16:30
Copy link
Member

@james-whiteside james-whiteside left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM apart from:

  • As the readme is specially treated on GitHub and in IDEs, it would be nice if the contents of the sample notebook could be displayed there, even if it's just a verbatim copy of the sample notebook as-rendedered.
  • It would be nice to have variable interpolation back, which is gone unless I'm mistaken. I also don't really like the idea of setting the result to a top-level namespace variable, which may have unintended behaviour. If you don't like providing the variable name as an argument, perhaps it could be accessed via a last_result class variable of the module instead? Moving values in and out of different modules and extensions is pretty key for Jupyter, so it's important that these features work smoothly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants