![\"Traqula](\"../../assets/white-on-red/logo-white-on-red-lettered-social.png\"){kind=logo}
\n\n \n
\n A query language transpiler framework for JavaScript\n
\n\n# SPARQL 1.1 AST, SPARQL 1.1 Algebra transformer\n\n[](https://www.npmjs.com/package/@traqula/algebra-sparql-1-1)\n\nModular transformer to transform a SPARQL 1.1 AST generated by Traqula to SPARQL 1.1 algebra.\nThere is also support for 'non-algebra' entities such as ASK, FROM, etc.\nto make sure the output contains all relevant information from the query.\n\n## Installation\n\n```bash\nnpm install @traqula/algebra-sparql-1-1\n```\n\nor\n\n```bash\nyarn add @traqula/algebra-sparql-1-1\n```\n\n## Import\n\nEither through ESM import:\n\n```javascript\nimport { toAst, toAlgebra } from '@traqula/algebra-sparql-1-1';\n```\n\n_or_ CJS require:\n\n```javascript\nconst { toAst, toAlgebra } = require('@traqula/algebra-sparql-1-1');\n```\n\n## Usage\n\nInput for the translation function should be a Traqula AST, by calling [Traqula parser](../parser-sparql-1-1).\nAlgebra operations are modeled as objects of the structure `{ name: string; input: Operation[] }`.\nThe transformation is detailed by [section 18.2 of the SPARQL specification](https://www.w3.org/TR/sparql11-query/#sparqlQuery).\n\nThe example bellow demonstrates this package usage where we parse a query string and transform it to algebra,\nfrom the algebra we will go back to a query string.\nNote that unlike the AST level, we do not provide [round tripping](../generator-sparql-1-1/README.md#round-tripping-generation) on algebra level.\n\n```typescript\nimport { Parser } from '@traqula/parser-sparql-1-1';\nimport { Generator } from '@traqula/generator-sparql-1-1';\nimport { toAlgebra, fromAlgebra } from '@traqula/algebra-sparql-1-1';\n// Initialize required variables.\nconst parser = new Parser();\nconst generator = new Generator();\nconst query = `SELECT * { ?s ?p ?o }`;\n\nconst ast = parser.parse(query);\nconst algebra = toAlgebra(ast);\n\nconst generatedAst = toAst(algebra);\nconst generatedQuery = generator.generate(generatedAst);\n```\n\n## Algebra Types\n\nThe algebra object contains a `types` object,\nwhich contains all possible values for the `type` field in the output results.\nBesides that it also contains all the TypeScript interfaces of the possible output results.\nThe output of the `toAlgebra` function will always be an `Algebra.Operation` instance.\n\nThe best way to see what output would be generated is to look in the [`test` folder](../../packages/test-utils/statics/algebra),\nwhere we have many SPARQL queries and their corresponding algebra output.\n\n### Modifying an Algebra Tree\n\nTraqula's core library provides a way to easily modify trees.\nThis functionality is exported specifically for the algebra tree under the [mapOperation](../../packages/algebra-transformations-1-1/lib/util.ts#L75) function in `@traqula/algebra-transformations-1-1`.\n\nQuery engines such as [Comunica](https://comunica.dev/) use the algebra operators as a way to guide the execution of a query.\nQuery execution may be optimized by manipulating the query operations in the algebra tree e.g.\n[filter pushdown](https://github.com/comunica/comunica/blob/master/packages/actor-optimize-query-operation-filter-pushdown/lib/ActorOptimizeQueryOperationFilterPushdown.ts), and for this task the `mapOperation` function is be instrumental.\n\nFurthermore, using `toAst`, one can convert an algebra tree to an AST, which can in turn be used to generate a SPARQL query using the [@traqula/generator-sparql-1-1](../generator-sparql-1-1).\nExactly this functionality is used in Comunica in order to support the SERVICE operator and support [federated queries](https://comunica.dev/docs/query/advanced/federation/).\n\n> [!NOTE]\n> Whether you manipulate queries on AST level or algebra level is entirely use case dependent.\n> AST level provides full control over the query that will be generated, but provides no abstraction.\n> Algebra level provides abstraction over the grammatical component of the language, allowing you to focus on the functional component, but leaves no control over the generated query string.\n\n## Deviations from the spec\n\nThis implementation tries to stay as close to the SPARQL 1.1 [specification](https://www.w3.org/TR/sparql11-query/#sparqlDefinition),\nbut some changes were made for ease of use.\nThese are mostly based on the Jena ARQ [implementation](https://jena.apache.org/documentation/query/).\nWhat follows is a non-exhaustive list of deviations:\n\n#### Named parameters\n\nThis is the biggest visual change.\nThe functions no longer take an ordered list of parameters but a named list instead.\nThe reason for this is to prevent having to memorize the order of parameters and also\ndue to seeing some differences between the spec and the Jena ARQ SSE output when ordering parameters.\n\n#### Multiset/List conversion\n\nThe functions `toMultiset` and `toList` have been removed for brevity.\nConversions between the two are implied by the operations used.\n\n#### Quads\n\nThe `translate` function has an optional second parameter\nindicating whether patterns should be translated to triple or quad patterns.\nIn the case of quads the `graph` operation will be removed\nand embedded into the patterns it contained.\nThe default value for this parameter is `false`.\n```\nPREFIX :