diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/graql.cabal b/graql.cabal new file mode 100644 --- /dev/null +++ b/graql.cabal @@ -0,0 +1,47 @@ +name: graql +version: 0.1.0.0 +synopsis: Execute Graql queries on a Grakn graph +description: A library for building and executing Graql queries on a + Grakn knowledge graph. +license: Apache-2.0 +license-file: LICENSE +homepage: https://github.com/graknlabs/graql-haskell +author: Felix Chapman +maintainer: felix@grakn.ai +category: Database,Graphs +build-type: Simple +extra-source-files: test/Example.lhs +cabal-version: >=1.10 + +library + build-depends: base >= 4.7 && < 5 + , containers == 0.5.* + , process == 1.4.* + , aeson == 1.0.* + , scientific == 0.3.* + , text == 1.2.* + , regex-posix == 0.95.* + hs-source-dirs: src + exposed-modules: Graql + , Graql.Shell + other-modules: Graql.Util + , Graql.Query + , Graql.Pattern + , Graql.Property + default-language: Haskell2010 + + default-extensions: OverloadedStrings + +test-suite test + type: exitcode-stdio-1.0 + main-is: Main.hs + hs-source-dirs: test + build-depends: base >= 4.7 && < 5 + , graql + , hspec + , text == 1.2.* + , markdown-unlit + other-modules: Example + default-language: Haskell2010 + ghc-options: -pgmL markdown-unlit + default-extensions: OverloadedStrings diff --git a/src/Graql.hs b/src/Graql.hs new file mode 100644 --- /dev/null +++ b/src/Graql.hs @@ -0,0 +1,38 @@ +module Graql + ( MatchQuery + , Var + , Name + , Value (..) + , match + , select + , distinct + , limit + , var + , name + , isa + , (-:) + , (.:) + , rp + , (<:) + , rel + , has + , hasText + , var_ + ) where + +import Graql.Property +import Graql.Pattern +import Graql.Query +import Data.Text (Text) + +-- |Specify a property has a particular type +(-:) :: (IsPattern p, IsVarOrName a) => p -> a -> Pattern +(-:) = isa + +-- |Shorthand to define a relation +rel :: IsRolePlayer a => [a] -> Pattern +rel = (var_ <:) + +-- |Specify a property has a resource +hasText :: (IsPattern p) => p -> Name -> Text -> Pattern +hasText = has diff --git a/src/Graql/Pattern.hs b/src/Graql/Pattern.hs new file mode 100644 --- /dev/null +++ b/src/Graql/Pattern.hs @@ -0,0 +1,62 @@ +module Graql.Pattern + ( Pattern + , IsPattern + , var_ + , isa + , (<:) + , has + , toPattern + ) where + +import Graql.Util +import Graql.Property + +-- |A pattern to find in the graph +data Pattern = Pattern (Maybe VarOrName) [Property] + +-- |Represents things that can be patterns +class IsPattern a where + toPattern :: a -> Pattern + +-- |Create an anonymous variable +var_ :: Pattern +var_ = Pattern Nothing [] + +-- |Specify a property has a particular type +isa :: (IsPattern p, IsVarOrName a) => p -> a -> Pattern +patt `isa` x = addProperty patt (Isa $ toVarOrName x) + +-- |Specify a property is a relation between other variables +(<:) :: (IsPattern p, IsRolePlayer a) => p -> [a] -> Pattern +patt <: cs = addProperty patt (Rel $ map toRolePlayer cs) + +-- |Specify a property has a resource +has :: (IsPattern p, IsResource a) => p -> Name -> a -> Pattern +has patt rt v = addProperty patt (Has rt $ toResource v) + + +showProps :: Show a => [a] -> String +showProps = spaces . reverse + +addPropToPattern :: Pattern -> Property -> Pattern +addPropToPattern (Pattern name props) prop = Pattern name (prop : props) + +addProperty :: IsPattern a => a -> Property -> Pattern +addProperty = addPropToPattern . toPattern + + +instance Show Pattern where + show (Pattern v [] ) = v `with` "" ++ ";" + show (Pattern v props) = v `with` " " ++ showProps props ++ ";" + +instance IsPattern Pattern where + toPattern = id + +instance IsPattern Var where + toPattern = toPattern . toVarOrName + +instance IsPattern Name where + toPattern = toPattern . toVarOrName + +instance IsPattern VarOrName where + toPattern v = Pattern (Just v) [] diff --git a/src/Graql/Property.hs b/src/Graql/Property.hs new file mode 100644 --- /dev/null +++ b/src/Graql/Property.hs @@ -0,0 +1,151 @@ +module Graql.Property + ( Property (..) + , Var + , Name + , VarOrName + , Value (..) + , IsVarOrName + , IsRolePlayer + , IsResource + , var + , name + , (.:) + , rp + , toVarOrName + , toRolePlayer + , toResource + ) where + +import Graql.Util +import Data.Text (Text, unpack) +import Data.Scientific (Scientific) +import Text.Regex.Posix ((=~)) +import Control.Applicative (empty) +import Data.Aeson (FromJSON, FromJSONKey, + FromJSONKeyFunction (FromJSONKeyText), + parseJSON) +import qualified Data.Aeson as Aeson + +-- |A property of a concept +data Property = Isa VarOrName + | NameProperty Name + | Rel [RolePlayer] + | Has Name (Either Value Var) + +-- |A variable name wildcard that will represent a concept in the results +data Var = Var Text deriving (Eq, Ord) + +-- |A name of something in the graph +data Name = Name Text + +-- |Something that may be a variable name or a type name +data VarOrName = VarName Var | TypeName Name + +-- |A value of a resource +data Value = ValueString Text | ValueNumber Scientific | ValueBool Bool + +-- |A casting, relating a role type and role player +data RolePlayer = RolePlayer (Maybe VarOrName) Var + +-- |Something that can be converted into a variable or a type name +class IsVarOrName a where + toVarOrName :: a -> VarOrName + +-- |Something that can be converted into a casting +class IsRolePlayer a where + toRolePlayer :: a -> RolePlayer + +-- |Something that can be converted into a resource value or variable +class IsResource a where + toResource :: a -> Either Value Var + +-- |Create a variable +var :: Text -> Var +var = Var + +-- |Create a name of something in the graph +name :: Text -> Name +name = Name + +-- |A casting in a relation between a role type and a role player +(.:) :: IsVarOrName a => a -> Var -> RolePlayer +rt .: player = RolePlayer (Just $ toVarOrName rt) player + +-- |A casting in a relation without a role type +rp :: Var -> RolePlayer +rp = RolePlayer Nothing + + +nameRegex :: String +nameRegex = "^[a-zA-Z_][a-zA-Z0-9_-]*$" + +instance Show Property where + show (Isa varOrName ) = "isa " ++ show varOrName + show (NameProperty n) = "type-name " ++ show n + show (Rel castings ) = "(" ++ commas castings ++ ")" + show (Has rt value ) = "has " ++ show rt ++ " " ++ showEither value + +instance Show RolePlayer where + show (RolePlayer roletype player) = roletype `with` ": " ++ show player + +instance Show Value where + show (ValueString text) = show text + show (ValueNumber num ) = show num + show (ValueBool bool) = show bool + +instance Show Name where + show (Name text) + | str =~ nameRegex = str + | otherwise = show text + where str = unpack text + +instance Show Var where + show (Var v) = '$' : unpack v + +instance Show VarOrName where + show (VarName v) = show v + show (TypeName t) = show t + +instance IsVarOrName Var where + toVarOrName = VarName + +instance IsVarOrName Name where + toVarOrName = TypeName + +instance IsRolePlayer RolePlayer where + toRolePlayer = id + +instance IsRolePlayer Var where + toRolePlayer = rp + +instance IsResource Var where + toResource = Right + +instance IsResource Text where + toResource = Left . ValueString + +instance IsResource Scientific where + toResource = Left . ValueNumber + +instance IsResource Bool where + toResource = Left . ValueBool + +instance FromJSON Value where + parseJSON (Aeson.String s) = return $ ValueString s + parseJSON (Aeson.Number n) = return $ ValueNumber n + parseJSON (Aeson.Bool b) = return $ ValueBool b + parseJSON _ = empty + +instance FromJSON Name where + parseJSON (Aeson.String s) = return $ name s + parseJSON _ = empty + +instance FromJSON Var where + parseJSON (Aeson.String s) = return $ var s + parseJSON _ = empty + +instance FromJSONKey Var where + fromJSONKey = FromJSONKeyText var + +showEither :: (Show a, Show b) => Either a b -> String +showEither = either show show diff --git a/src/Graql/Query.hs b/src/Graql/Query.hs new file mode 100644 --- /dev/null +++ b/src/Graql/Query.hs @@ -0,0 +1,41 @@ +module Graql.Query + ( MatchQuery + , match + , select + , limit + , distinct + ) where + +import Graql.Util +import Graql.Pattern +import Graql.Property + +-- |A Graql 'match' query that finds a pattern in the graph +data MatchQuery = Match [Pattern] + | Select MatchQuery [Var] + | Limit MatchQuery Integer + | Distinct MatchQuery + +-- |Create a match query by providing a list of patterns +match :: IsPattern a => [a] -> MatchQuery +match = Match . map toPattern + +-- |Select variables from a match query, intended to be used infix +select :: [Var] -> MatchQuery -> MatchQuery +select = flip Select + +-- |Limit a match query, intended to be used infix +limit :: Integer -> MatchQuery -> MatchQuery +limit = flip Limit + +-- |Retrieve only distinct results from a match query +distinct :: MatchQuery -> MatchQuery +distinct = Distinct + + +instance Show MatchQuery where + show (Match patts ) = "match " ++ spaces patts + show (Select mq vars) = show mq ++ " select " ++ commas vars ++ ";" + show (Limit mq lim ) = show mq ++ " limit " ++ show lim ++ ";" + show (Distinct mq ) = show mq ++ " distinct;" + diff --git a/src/Graql/Shell.hs b/src/Graql/Shell.hs new file mode 100644 --- /dev/null +++ b/src/Graql/Shell.hs @@ -0,0 +1,65 @@ +module Graql.Shell + ( Concept + , Result + , cid + , ctype + , value + , runFile + , runMatch + , migrateCsv + ) where + +import Control.Applicative (empty) +import Data.Aeson (FromJSON, eitherDecodeStrict, parseJSON, + (.:), (.:?)) +import qualified Data.Aeson as Aeson +import Data.Map (Map) +import Data.Text (Text, pack) +import Data.Text.Encoding (encodeUtf8) +import Graql hiding ((.:)) +import System.Process (callProcess, readProcessWithExitCode) + +-- |A concept in the graph +data Concept = Concept { cid :: Text, cname :: Maybe Name, ctype :: Maybe Name, value :: Maybe Value } + deriving Show + +-- |A result of a match query, binding variables to concepts +type Result = Map Var Concept + +-- |Run the given file path on the database, ignoring the output +runFile :: FilePath -> IO () +runFile path = callProcess "graql.sh" ["-f", path] + +-- |Run a match query on the graph +runMatch :: MatchQuery -> IO [Result] +runMatch q = do + result <- parseResults <$> runGraql q + either fail return result + +-- |Run the CSV migrator using the given csv file, template file and separator +migrateCsv :: FilePath -> FilePath -> String -> IO () +migrateCsv file template separator = + callProcess "migration.sh" args + where args = ["csv", "-i", file, "-t", template, "-s", separator] + + +type Error = String + +runGraql :: MatchQuery -> IO String +runGraql q = do + (_, stdout, stderr) <- readProcessWithExitCode "graql.sh" args "" + if length (lines stderr) <= 1 + then return stdout + else fail stderr + where args = ["-e", show q, "-o", "json"] + +parseResults :: String -> Either Error [Result] +parseResults = mapM parseResult . lines + +parseResult :: String -> Either Error Result +parseResult = eitherDecodeStrict . encodeUtf8 . pack + +instance FromJSON Concept where + parseJSON (Aeson.Object obj) = + Concept <$> (obj .: "id") <*> (obj .:? "name") <*> (obj .:? "isa") <*> (obj .:? "value") + parseJSON _ = empty diff --git a/src/Graql/Util.hs b/src/Graql/Util.hs new file mode 100644 --- /dev/null +++ b/src/Graql/Util.hs @@ -0,0 +1,20 @@ +module Graql.Util + ( with + , commas + , spaces + ) where + +import Data.List (intercalate) + +with :: Show a => Maybe a -> String -> String +(Just val) `with` suffix = show val ++ suffix +Nothing `with` _ = "" + +commas :: Show a => [a] -> String +commas = interList ", " + +spaces :: Show a => [a] -> String +spaces = interList " " + +interList :: Show a => String -> [a] -> String +interList sep = intercalate sep . map show diff --git a/test/Example.lhs b/test/Example.lhs new file mode 100644 --- /dev/null +++ b/test/Example.lhs @@ -0,0 +1,58 @@ +A simple library for building and executing Graql queries. + +Import the modules: + +```haskell +module Example where + +import Graql +import Graql.Shell + +import Data.Function ((&)) +``` + +Define the type names: + +```haskell +person = name "person" +husband = name "husband" +wife = name "wife" +marriage = name "marriage" +``` + +Define the variables: + +```haskell +x = var "x" +y = var "y" +``` + +We can translate the following query into Haskell: + +```graql +match $x isa person, (husband: $x, wife: $y) isa marriage; select $y; +``` + +```haskell +query = match + [ x `isa` person + , rel [husband .: x, wife .: y] `isa` marriage + ] & select [y] +``` + +We can also use infix functions like `(-:)` instead of `isa`: + +```haskell +otherQuery = match + [ x -: person + , rel [husband .: x, wife .: y] -: marriage + ] & select [y] +``` + +To execute and print the results of our query: + +```haskell +main = do + result <- runMatch query + print result +``` diff --git a/test/Main.hs b/test/Main.hs new file mode 100644 --- /dev/null +++ b/test/Main.hs @@ -0,0 +1,81 @@ +module Main where + +import Data.Function ((&)) +import Test.Hspec +import Graql +import qualified Example + +main :: IO () +main = hspec $ do + + it "a simple query string representation" $ + match [x `isa` person] ~= "match $x isa person;" + + it "a relation query string representation" $ + match [rel [x, y]] ~= "match ($x, $y);" + + it "a relation query string representation with types" $ + match [rel [husband.: x, wife.: y] -: marriage] + ~= "match (husband: $x, wife: $y) isa marriage;" + + it "a resource query string representation" $ + match [x `hasText` firstName $ "Bob"] + ~= "match $x has first-name \"Bob\";" + + it "multiple patterns" $ + match [x-:person, y-:firstName] + ~= "match $x isa person; $y isa first-name;" + + it "select query with type" $ + match [x -: y] & select [x, y] + ~= "match $x isa $y; select $x, $y;" + + it "mix role types" $ + match [rel [husband.: x, rp y]] ~= "match (husband: $x, $y);" + + it "limit and distinct" $ + match [x -: person] & distinct & limit 10 + ~= "match $x isa person; distinct; limit 10;" + + it "type of type" $ + match [person -: x] ~= "match person isa $x;" + + it "reify a relation" $ + match [x <: [y, z]] ~= "match $x ($y, $z);" + + it "match just a variable" $ + match [x] ~= "match $x;" + + it "example query output" $ + Example.query + ~= "match $x isa person; (husband: $x, wife: $y) isa marriage; select $y;" + + +x :: Var +x = var "x" + +y :: Var +y = var "y" + +z :: Var +z = var "z" + +person :: Name +person = name "person" + +firstName :: Name +firstName = name "first-name" + +marriage :: Name +marriage = name "marriage" + +husband :: Name +husband = name "husband" + +wife :: Name +wife = name "wife" + +infixr 0 ~= + +(~=) :: MatchQuery -> String -> Expectation +(~=) = shouldBe . show