From 941eb873c053ac291906e8bcdb52db8d12104592 Mon Sep 17 00:00:00 2001 From: Frank Urbach <33724682+FrankUrbach@users.noreply.github.com> Date: Sun, 3 Oct 2021 17:13:36 +0200 Subject: [PATCH] use the corrected docs by Mark (#121) * use the corrected docs by Mark * Update guide.md with compatibility table and edits * Updated change.log * Fixed typo * Update examples.md Co-authored-by: M. Schulze --- docs/make.jl | 2 +- docs/src/.DS_Store | Bin 6148 -> 6148 bytes docs/src/changelog.md | 16 ++- docs/src/contributing.md | 8 +- docs/src/examples.md | 11 ++ docs/src/guide.md | 210 ++++++++++++++++++++++++++++++++------- 6 files changed, 209 insertions(+), 38 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 745a10db..643d1959 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -2,7 +2,7 @@ using TypeDBClient using Documenter -@info "Makeing documentation..." +@info "Making documentation..." makedocs(; modules=[TypeDBClient], clean = true, diff --git a/docs/src/.DS_Store b/docs/src/.DS_Store index 21dc07c97503793be3f93b56315ccc144e8a8696..520d8afb3a74e03a159054dd61352da3dab4a730 100644 GIT binary patch delta 203 zcmZoMXfc=|#>B`mu~2NHo+2ab!~pAw2O5BMk4!xqLn1>l5T-JeFcjyc8wMxm=N2%4 z08;{pMv>3WcX3I|$xi}`b8xIWe`9vbVMk0gDFoFNWWelU1z9v<CJzu~2NHo+2aT!~knX#>qU4G7~cvZ$7~2&Ni{3bTc~#KL=3F=8cTs cnJ4p$=yEbLFfbedVur~!JkpzEM3yiE0Q)c#djJ3c diff --git a/docs/src/changelog.md b/docs/src/changelog.md index 9db0722a..9ce7e059 100644 --- a/docs/src/changelog.md +++ b/docs/src/changelog.md @@ -5,14 +5,26 @@ CurrentModule = TypeDBClient # Changelog ## lets list em here +*** +03.10.2021 + +- more work on docs +- release preparations + +*** +27.09.2021 + +- changed the client to use threading where it is suitable +- extended the docs + *** 25.06.2021 - updated docs - trigger CI - + *** 08.11.2020 - created project logo -- set up initial docs and guidelines \ No newline at end of file +- set up initial docs and guidelines diff --git a/docs/src/contributing.md b/docs/src/contributing.md index a48f6b88..f5ca8a79 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -12,12 +12,18 @@ There is the [Workbase] (https://docs.vaticle.com/docs/workbase/overview) the [T There are clients for the following languages: Java, Node.js and Python. -We are going to build the Julia client here. +This is the new community driven Julia client. ## Workflow guidance & roadmap Our reference client is the [Java version](https://docs.vaticle.com/docs/client-api/java). +The roadmap for TypeDBClient.jl (01.10.2021): + +- completing the client with the cluster functionality (commercial product by Vaticle) +- improving speed +- making multithreading possible and threadsafe + The roadmap for TypeDBClient.jl (24.01.2021): - writing a HTTP/2 and gRPC implementation in Julia (done) diff --git a/docs/src/examples.md b/docs/src/examples.md index e69de29b..b58fd675 100644 --- a/docs/src/examples.md +++ b/docs/src/examples.md @@ -0,0 +1,11 @@ +# Examples + +For a quick example based introduction, you can refer to the folder examples and check out the files there. + +However, if you like to watch a Video, showing how to work with the client in a Notebook, you can watch this recording: + +[A TypeDB Client Interface in Julia | TypeDBClient.jl](https://youtu.be/liNnm1nShCg?t=1262) + +Have fun and feel free to ask questions in our community channel on Discord! + +TypeDBClient.jl Discord channel: [Invite link](https://discord.gg/fYgKmGDukH) diff --git a/docs/src/guide.md b/docs/src/guide.md index eaf1f4c6..e437e7ed 100644 --- a/docs/src/guide.md +++ b/docs/src/guide.md @@ -1,94 +1,236 @@ ```@meta CurrentModule = TypeDBClient ``` - # User Guide -**This is just a preview yet** - ## Installation -To use this client, you need a compatible TypeDB Server running. Visit the Compatibility Table +To use this client, you need a compatible TypeDB Server running. +You can find install instructions in the [TypeDB Documentation](https://docs.vaticle.com/docs/running-typedb/install-and-run). -This pkg is not yet registered on the JuliaHub. As of now you would need to install it directly from the GitHub repo. +## Compatibility table: + +| TypeDBClient.jl | TypeDB | TypeDB Cluster | Julia | +|:--------------:|:-----------:|:------------:|:------------:| +| 0.1.0 | 2.4 | - | >=1.6 Inside the Julia REPL, type ] to enter the Pkg REPL mode then run -`pkg> dev https://github.com/Humans-of-Julia/TypeDBClient.jl` +`pkg> add TypeDBClient` ## Quickstart -First make sure, the TypeDB server is running. It is described here in the [TypeDB Documentation](https://docs.vaticle.com/docs/running-typedb/install-and-run). +First make sure, the TypeDB server is running. +See [Start the TypeDB Server](https://docs.vaticle.com/docs/running-typedb/install-and-run#start-the-typedb-server) section. -In the Julia REPL or in your source run +In the Julia REPL or in your source code run: -` using TypeDBCLient` +`using TypeDBClient` You have two choices: -* If you are only interested on working interactivly on wrangling some data interactivly you can use the more simplified API. An example for this is: +* If you are only interested in working interactivly, you can use the more simplified API. An example for this is: ```julia using TypeDBClient: dbconnect, open, read, write, match, insert, commit, create_database +# Connecting the client to TypeDB dbconnect("127.0.0.1") do client -# The client section where all commands with the client -# are possible - # Here the creation of a database + # Creation of a database create_database(client, "my-typedb") - # Open the session + # Opening the session open(client, "my-typedb") do session # Open a write transaction write(session) do transaction - # make a insert with a TypeQL string + # Make a insert with a TypeQL string insert(transaction, raw"insert $_ isa person;") - #committing the transaction. + # Committing the transaction. commit(transaction) end # Open a read session read(session) do transaction - # make a match request with a TypeQL string + # Make a match request with a TypeQL string answers = match(transaction, raw"match $p isa person;") end end end ``` -For working with data using TypeQL please refer to the syntax on [TypeQL Documentation](https://docs.vaticle.com/docs/query/overview) +For working with data using TypeQL, please refer to the syntax on [TypeQL Documentation](https://docs.vaticle.com/docs/query/overview) + +* If you want the full stack at your fingertips, then you can use the following commands: -* You want the full stack at your fingertips. Then you can use the following commands: ```julia using TypeDBClient -# only for convencience reasons, you can write the full name if you want +# Only for convencience reasons, you can write the full name if you want g = TypeDBClient -#create a client + +# Create a client client = g.CoreClient("127.0.0.1",1729) -# create a database called typedb if the database isn't on the server +# Create a database called typedb if the database isn't already created by you previously. g.create_database(client, "typedb") -# Open a session to write in the schema section of the database. -# Be careful if you work with a schema session. No more session are allowed -# until you close this session. Closing a session is essentially. Don't forget this -# at the end of your work -session = g.CoreSession(client, "typedb" , g.Proto.Session_Type.SCHEMA, request_timout=Inf) +#= Open a session to write in the schema section of the database. +Be careful if you work with a schema session. No more sessions are allowed +until you close this session. Closing a session is mandatory. Don't forget this +at the end of your work.=# +session = g.CoreSession(client, "typedb" , g.Proto.Session_Type.SCHEMA, request_timeout=Inf) -# open a write transaction +# Open a write transaction transaction = g.transaction(session, g.Proto.Transaction_Type.WRITE) -# make a query in the database -# The result of this query will be a vector of ConceptMap. From there you can access the -# data as you want. +#= Make a query in the database +The result of this query will be a vector of ConceptMap. +From there you can access the data as you want.=# results = g.match(transaction, raw"""match $x sub thing;""") -# If you want work further in with the session, go ahead else close the session +# If you want to work further in the session, go ahead, else close the session. close(session) ``` -If you want use the full potential of the client you should read the documentation +If you want to use the full potential of the client you should read the documentation of the API functions. There you will find all you need for working programmatically in the database. -Otherwise it is even possible to get most of the time equally results using TypeQL. +Otherwise, it is even possible to get equal results using TypeQL. ```@autodocs Modules = [TypeDBClient] ``` + +## User API + +* delete + + There are some delete functions: + * database + + [`delete_database(client::CoreClient, database_name::String)`](@ref) + + * type + + [`delete(r::RemoteConcept{C,T}) where {C <:AbstractThingType, T <: AbstractCoreTransaction}`](@ref) + + Any type can be deleted with this function. Be aware that only types which have no instances + in the database can be deleted. + + +* get_has + + [`get_owns(r::RemoteConcept{C,T}, value_type::Optional{EnumType}=nothing,keys_only::Bool=false) where {C <: AbstractThingType,T <: AbstractCoreTransaction}`](@ref) + + +* get_instances + + [`get_instances(r::RemoteConcept{C,T}) where + {C <: AbstractThingType,T <: AbstractCoreTransaction}`](@ref) + +* get_owns + + [`get_owns( + r::RemoteConcept{C,T}, + value_type::Optional{EnumType}=nothing, + keys_only::Bool=false + ) where {C <: AbstractThingType,T <: AbstractCoreTransaction}`](@ref) + + +* get_owners + + * Attribute + + [`get_owners(transaction::AbstractCoreTransaction, + attribute::AbstractAttribute, + thing_type::Optional{AbstractThingType} = nothing)`](@ref) + + * AttributeType + + [`get_owners(r::RemoteConcept{C,T}, only_key = false) where { + C <: AbstractAttributeType, T <: AbstractCoreTransaction}`](@ref) + + +* get_plays + + [`get_plays(r::RemoteConcept{C,T}) where + {C <: AbstractThingType,T <: AbstractCoreTransaction}`](@ref) + + +* get_regex + + [`get_regex(r::RemoteConcept{C,T}) where { + C <: AbstractAttributeType, T <: AbstractCoreTransaction}`](@ref) + + +* get_rule + + [`get_rule(log_mgr::AbstractLogicManager, label::String)`](@ref) + + +* get_rules + + [`get_rules(log_mgr::AbstractLogicManager)`](@ref) + + +* get_subtypes + + [`get_subtypes(r::RemoteConcept{C,T}) where + {C <: AbstractType,T <: AbstractCoreTransaction}`](@ref) + +* get_supertype + + [`get_supertype( + r::RemoteConcept{C,T}) where {C <: AbstractType,T <: AbstractCoreTransaction}`](@ref) + +* get_supertypes + + [`get_supertypes(r::RemoteConcept{C,T}) where + {C <: AbstractType,T <: AbstractCoreTransaction}`](@ref) + +* set_abstract + + [`set_abstract(r::RemoteConcept{C,T}) where + {C <: AbstractThingType,T <: AbstractCoreTransaction}`](@ref) + +* set_has + + [`set_has(transaction::AbstractCoreTransaction, thing::AbstractThing, attribute::Attribute)`](@ref) + +* set_label + + [`set_label(r::RemoteConcept{C,T}, new_label_name::String) where + {C <: AbstractType,T <: AbstractCoreTransaction}`](@ref) + +* set_owns + + [`set_owns( + r::RemoteConcept{C,T}, + attribute_type::AbstractType, + is_key::Bool=false, + overriden_type::Optional{AbstractType}=nothing + ) where {C <: AbstractType,T <: AbstractCoreTransaction}`](@ref) + +* set_plays + + [`function set_plays( + r::RemoteConcept{C,T}, + role_type::AbstractRoleType, + overridden_role_type::Optional{AbstractRoleType}=nothing + ) where {C <: AbstractThingType,T <: AbstractCoreTransaction}`](@ref) + +* set_regex + + [``set_regex(r::RemoteConcept{C,T}, regex::Optional{AbstractString}) where { + C <: AbstractAttributeType, T <: AbstractCoreTransaction}](@ref) + +* set_supertype + + [`set_supertype(r::RemoteConcept{C,T}, + super_type::AbstractThingType) where + {C <: AbstractThingType,T <: AbstractCoreTransaction}`](@ref) + +* unset_abstract + + [`unset_abstract(r::RemoteConcept{C,T}) where + {C <: AbstractThingType,T <: AbstractCoreTransaction}`](@ref) + +* unset_has + + [`unset_has(transaction::AbstractCoreTransaction, thing::AbstractThing, attribute::Attribute)`](@ref)