CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="generator" content="Asciidoctor 2.0.18"> <title>Recipes</title> <style> /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you 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. */ /*! normalize.css v2.1.2 | MIT License | git.io/normalize */ /* ========================================================================== HTML5 display definitions ========================================================================== */ /** Correct `block` display not defined in IE 8/9. */ @import url(http://cdnjs.cloudflare.com/ajax/libs/font-awesome/3.2.1/css/font-awesome.css); article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; } /** Correct `inline-block` display not defined in IE 8/9. */ audio, canvas, video { display: inline-block; } /** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */ audio:not([controls]) { display: none; height: 0; } /** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */ [hidden], template { display: none; } script { display: none !important; } /* ========================================================================== Base ========================================================================== */ /** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */ html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ } /** Remove default margin. */ body { margin: 0; } /* ========================================================================== Links ========================================================================== */ /** Remove the gray background color from active links in IE 10. */ a { background: transparent; } /** Address `outline` inconsistency between Chrome and other browsers. */ a:focus { outline: thin dotted; } /** Improve readability when focused and also mouse hovered in all browsers. */ a:active, a:hover { outline: 0; } /* ========================================================================== Typography ========================================================================== */ /** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */ h1 { font-size: 2em; margin: 0.67em 0; } /** Address styling not present in IE 8/9, Safari 5, and Chrome. */ abbr[title] { border-bottom: 1px dotted; } /** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */ b, strong { font-weight: bold; } /** Address styling not present in Safari 5 and Chrome. */ dfn { font-style: italic; } /** Address differences between Firefox and other browsers. */ hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; } /** Address styling not present in IE 8/9. */ mark { background: #ff0; color: #000; } /** Correct font family set oddly in Safari 5 and Chrome. */ code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; } /** Improve readability of pre-formatted text in all browsers. */ pre { white-space: pre-wrap; } /** Set consistent quote types. */ q { quotes: "\201C" "\201D" "\2018" "\2019"; } /** Address inconsistent and variable font size in all browsers. */ small { font-size: 80%; } /** Prevent `sub` and `sup` affecting `line-height` in all browsers. */ sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; } sup { top: -0.5em; } sub { bottom: -0.25em; } /* ========================================================================== Embedded content ========================================================================== */ /** Remove border when inside `a` element in IE 8/9. */ img { border: 0; } /** Correct overflow displayed oddly in IE 9. */ svg:not(:root) { overflow: hidden; } /* ========================================================================== Figures ========================================================================== */ /** Address margin not present in IE 8/9 and Safari 5. */ figure { margin: 0; } /* ========================================================================== Forms ========================================================================== */ /** Define consistent border, margin, and padding. */ fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; } /** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */ legend { border: 0; /* 1 */ padding: 0; /* 2 */ } /** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */ button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ } /** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */ button, input { line-height: normal; } /** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */ button, select { text-transform: none; } /** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */ button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ } /** Re-set default cursor for disabled elements. */ button[disabled], html input[disabled] { cursor: default; } /** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */ input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ } /** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */ input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; } /** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */ input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; } /** Remove inner padding and border in Firefox 4+. */ button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; } /** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */ textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ } /* ========================================================================== Tables ========================================================================== */ /** Remove most spacing between table cells. */ table { border-collapse: collapse; border-spacing: 0; } meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; } meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; } meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; } *, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; } html, body { font-size: 100%; } body { background: white; color: #222222; padding: 0; margin: 0; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; } a:hover { cursor: pointer; } img, object, embed { max-width: 100%; height: auto; } object, embed { height: 100%; } img { -ms-interpolation-mode: bicubic; } #map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; } .left { float: left !important; } .right { float: right !important; } .text-left { text-align: left !important; } .text-right { text-align: right !important; } .text-center { text-align: center !important; } .text-justify { text-align: justify !important; } .hide { display: none; } .antialiased, body { -webkit-font-smoothing: antialiased; } img { display: inline-block; vertical-align: middle; } textarea { height: auto; min-height: 50px; } select { width: 100%; } p.lead, .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; } .subheader, #content #toctitle, .admonitionblock td.content > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .mathblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, .sidebarblock > .title, .tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title, .tableblock > caption { line-height: 1.4; color: #6c818f; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; } /* Typography resets */ div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; } /* Default Link Styles */ a { color: #444444; text-decoration: underline; line-height: inherit; } a:hover, a:focus { color: #111111; } a img { border: none; } /* Default paragraph styles */ p { font-family: inherit; font-weight: normal; font-size: 1em; line-height: 1.5; margin-bottom: 1.25em; text-rendering: optimizeLegibility; } p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; } /* Default header styles */ h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: ff-meta-web-pro-1, ff-meta-web-pro-2, Arial, "Helvetica Neue", sans-serif; font-weight: bold; font-style: normal; color: #465158; text-rendering: optimizeLegibility; margin-top: 1em; margin-bottom: 0.5em; line-height: 1.2125em; } h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #909ea7; line-height: 0; } h1 { font-size: 2.125em; } h2 { font-size: 1.6875em; } h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; } h4 { font-size: 1.125em; } h5 { font-size: 1.125em; } h6 { font-size: 1em; } hr { border: solid #dddddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; } /* Helpful Typography Defaults */ em, i { font-style: italic; line-height: inherit; } strong, b { font-weight: bold; line-height: inherit; } small { font-size: 60%; line-height: inherit; } code { font-family: "Consolas", "Deja Vu Sans Mono", "Bitstream Vera Sans Mono", monospace; font-weight: normal; color: #444444; } /* Lists */ ul, ol, dl { font-size: 1em; line-height: 1.5; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; } ul, ol { margin-left: 0; } ul.no-bullet, ol.no-bullet { margin-left: 0; } /* Unordered Lists */ ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ } ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; } ul.square { list-style-type: square; } ul.circle { list-style-type: circle; } ul.disc { list-style-type: disc; } ul.no-bullet { list-style: none; } /* Ordered Lists */ ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; } /* Definition Lists */ dl dt { margin-bottom: 0.3em; font-weight: bold; } dl dd { margin-bottom: 0.75em; } /* Abbreviations */ abbr, acronym { text-transform: uppercase; font-size: 90%; color: black; border-bottom: 1px dotted #dddddd; cursor: help; } abbr { text-transform: none; } /* Blockquotes */ blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; } blockquote cite { display: block; font-size: 0.8125em; color: #748590; } blockquote cite:before { content: "\2014 \0020"; } blockquote cite a, blockquote cite a:visited { color: #748590; } blockquote, blockquote p { line-height: 1.5; color: #909ea7; } /* Microformats */ .vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; } .vcard li { margin: 0; display: block; } .vcard .fn { font-weight: bold; font-size: 0.9375em; } .vevent .summary { font-weight: bold; } .vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; } @media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; } h1 { font-size: 2.75em; } h2 { font-size: 2.3125em; } h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; } h4 { font-size: 1.4375em; } } /* Print styles. Inlined to avoid required HTTP connection: www.phpied.com/delay-loading-your-print-css/ Credit to Paul Irish and HTML5 Boilerplate (html5boilerplate.com) */ .print-only { display: none !important; } @media print { * { background: transparent !important; color: #000 !important; /* Black prints faster: h5bp.com/s */ box-shadow: none !important; text-shadow: none !important; } a, a:visited { text-decoration: underline; } a[href]:after { content: " (" attr(href) ")"; } abbr[title]:after { content: " (" attr(title) ")"; } .ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { content: ""; } pre, blockquote { border: 1px solid #999; page-break-inside: avoid; } thead { display: table-header-group; /* h5bp.com/t */ } tr, img { page-break-inside: avoid; } img { max-width: 100% !important; } @page { margin: 0.5cm; } p, h2, h3, #toctitle, .sidebarblock > .content > .title { orphans: 3; widows: 3; } h2, h3, #toctitle, .sidebarblock > .content > .title { page-break-after: avoid; } .hide-on-print { display: none !important; } .print-only { display: block !important; } .hide-for-print { display: none !important; } .show-for-print { display: inherit !important; } } /* Tables */ table { background: white; margin-bottom: 1.25em; border: solid 0 #dddddd; } table thead, table tfoot { background: none; font-weight: bold; } table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 1px 8px 1px 5px; font-size: 1em; color: #222222; text-align: left; } table tr th, table tr td { padding: 1px 8px 1px 5px; font-size: 1em; color: #222222; } table tr.even, table tr.alt, table tr:nth-of-type(even) { background: none; } table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.5; } .clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; } .clearfix:after, .float-group:after { clear: both; } *:not(pre) > code { font-size: 0.95em; padding: 0; white-space: nowrap; background-color: #f2f2f2; border: 0 solid #dddddd; -webkit-border-radius: 6px; border-radius: 6px; text-shadow: none; } pre, pre > code { line-height: 1.2; color: inherit; font-family: "Consolas", "Deja Vu Sans Mono", "Bitstream Vera Sans Mono", monospace; font-weight: normal; } .keyseq { color: #333333; } kbd:not(.keyseq) { display: inline-block; color: black; font-size: 0.75em; line-height: 1.4; background-color: #F7F7F7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; margin: -0.15em 0.15em 0 0.15em; padding: 0.2em 0.6em 0.2em 0.5em; vertical-align: middle; white-space: nowrap; } .keyseq kbd:first-child { margin-left: 0; } .keyseq kbd:last-child { margin-right: 0; } .menuseq, .menu { color: black; } b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; } b.button:before { content: "["; padding: 0 3px 0 2px; } b.button:after { content: "]"; padding: 0 2px 0 3px; } p a > code:hover { color: #373737; } #header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; } #header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; } #header:after, #content:after, #footnotes:after, #footer:after { clear: both; } #header { margin-bottom: 2.5em; } #header > h1 { color: #111111; font-weight: bold; border-bottom: 1px solid #dddddd; margin-bottom: -28px; padding-bottom: 32px; } #header span { color: #909ea7; } #header #revnumber { text-transform: capitalize; } #header br { display: none; } #header br + span { padding-left: 3px; } #header br + span:before { content: "\2013 \0020"; } #header br + span.author { padding-left: 0; } #header br + span.author:before { content: ", "; } #toc { border-bottom: 1px solid #dddddd; padding-bottom: 1.25em; } #toc > ul { margin-left: 0.25em; } #toc ul.sectlevel0 > li > a { font-style: italic; } #toc ul.sectlevel0 ul.sectlevel1 { margin-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } #toc ul { list-style-type: none; } #toctitle { color: #6c818f; } @media only screen and (min-width: 768px) { body.toc2 { padding-left: 15em; padding-right: 0; } #toc.toc2 { position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #dddddd; border-bottom: 0; z-index: 1000; padding: 1em; height: 100%; overflow: auto; } #toc.toc2 #toctitle { margin-top: 0; font-size: 1.2em; } #toc.toc2 > ul { font-size: .90em; } #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; } #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; } body.toc2.toc-right { padding-left: 0; padding-right: 15em; } body.toc2.toc-right #toc.toc2 { border-right: 0; border-left: 1px solid #dddddd; left: auto; right: 0; } } @media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; } #toc.toc2 { width: 20em; } #toc.toc2 #toctitle { font-size: 1.375em; } #toc.toc2 > ul { font-size: 0.95em; } #toc.toc2 ul ul { padding-left: 1.25em; } body.toc2.toc-right { padding-left: 0; padding-right: 20em; } } #content #toc { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; border-width: 0; -webkit-border-radius: 6px; border-radius: 6px; } #content #toc > :first-child { margin-top: 0; } #content #toc > :last-child { margin-bottom: 0; } #content #toc a { text-decoration: none; } #content #toctitle { font-weight: bold; font-family: ff-meta-web-pro-1, ff-meta-web-pro-2, Arial, "Helvetica Neue", sans-serif; font-size: 1em; padding-left: 0.125em; } #footer { max-width: 100%; background-color: black; padding: 1.25em; } #footer-text { color: white; line-height: 1.35; } .sect1 { padding-bottom: 1.25em; } .sect1 + .sect1 { border-top: 1px solid #dddddd; } #content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; width: 1em; margin-left: -1em; display: block; text-decoration: none; visibility: hidden; text-align: center; font-weight: normal; } #content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: '\00A7'; font-size: .85em; vertical-align: text-top; display: block; margin-top: 0.05em; } #content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; } #content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #465158; text-decoration: none; } #content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #3b444a; } .imageblock, .literalblock, .listingblock, .mathblock, .verseblock, .videoblock { margin-bottom: 1.25em; } .admonitionblock td.content > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .mathblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, .sidebarblock > .title, .tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-align: left; font-weight: bold; } .tableblock > caption { text-align: left; font-weight: bold; white-space: nowrap; overflow: visible; max-width: 0; } table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; } .admonitionblock > table { border: 0; background: none; width: 100%; } .admonitionblock > table td.icon { text-align: center; width: 80px; } .admonitionblock > table td.icon img { max-width: none; } .admonitionblock > table td.icon .title { font-weight: bold; text-transform: uppercase; } .admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #dddddd; color: #909ea7; } .admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; } .exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 6px; border-radius: 6px; } .exampleblock > .content > :first-child { margin-top: 0; } .exampleblock > .content > :last-child { margin-bottom: 0; } .exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6, .exampleblock > .content p { color: #333333; } .exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6 { line-height: 1; margin-bottom: 0.625em; } .exampleblock > .content h1.subheader, .exampleblock > .content h2.subheader, .exampleblock > .content h3.subheader, .exampleblock > .content .subheader#toctitle, .sidebarblock.exampleblock > .content > .subheader.title, .exampleblock > .content h4.subheader, .exampleblock > .content h5.subheader, .exampleblock > .content h6.subheader { line-height: 1.4; } .exampleblock.result > .content { -webkit-box-shadow: 0 1px 8px #d9d9d9; box-shadow: 0 1px 8px #d9d9d9; } .sidebarblock { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; -webkit-border-radius: 6px; border-radius: 6px; } .sidebarblock > :first-child { margin-top: 0; } .sidebarblock > :last-child { margin-bottom: 0; } .sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6, .sidebarblock p { color: #333333; } .sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6 { line-height: 1; margin-bottom: 0.625em; } .sidebarblock h1.subheader, .sidebarblock h2.subheader, .sidebarblock h3.subheader, .sidebarblock .subheader#toctitle, .sidebarblock > .content > .subheader.title, .sidebarblock h4.subheader, .sidebarblock h5.subheader, .sidebarblock h6.subheader { line-height: 1.4; } .sidebarblock > .content > .title { color: #6c818f; margin-top: 0; line-height: 1.5; } .exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; } .literalblock pre:not([class]), .listingblock pre:not([class]) { background: #eeeeee; } .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border-width: 1px; border-style: solid; border-color: #cccccc; -webkit-border-radius: 6px; border-radius: 6px; padding: 0.5em; word-wrap: break-word; } .literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; } .literalblock pre > code, .literalblock pre[class] > code, .listingblock pre > code, .listingblock pre[class] > code { display: block; } @media only screen { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.76em; } } @media only screen and (min-width: 768px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.855em; } } @media only screen and (min-width: 1280px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.95em; } } .listingblock pre.highlight { padding: 0; } .listingblock pre.highlight > code { padding: 0.5em; } .listingblock > .content { position: relative; } .listingblock:hover code[class*=" language-"]:before { text-transform: uppercase; font-size: 0.9em; color: #999; position: absolute; top: 0.375em; right: 0.375em; } .listingblock:hover code.asciidoc:before { content: "asciidoc"; } .listingblock:hover code.clojure:before { content: "clojure"; } .listingblock:hover code.css:before { content: "css"; } .listingblock:hover code.groovy:before { content: "groovy"; } .listingblock:hover code.html:before { content: "html"; } .listingblock:hover code.java:before { content: "java"; } .listingblock:hover code.javascript:before { content: "javascript"; } .listingblock:hover code.python:before { content: "python"; } .listingblock:hover code.ruby:before { content: "ruby"; } .listingblock:hover code.sass:before { content: "sass"; } .listingblock:hover code.scss:before { content: "scss"; } .listingblock:hover code.xml:before { content: "xml"; } .listingblock:hover code.yaml:before { content: "yaml"; } .listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; } .listingblock.terminal pre .command:not([data-prompt]):before { content: '$'; } table.pyhltable { border: 0; margin-bottom: 0; } table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; } table.pyhltable td.code { padding-left: .75em; padding-right: 0; } .highlight.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #dddddd; } .highlight.pygments .lineno { display: inline-block; margin-right: .25em; } table.pyhltable .linenodiv { background-color: transparent !important; padding-right: 0 !important; } .quoteblock { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; } .quoteblock blockquote { margin: 0 0 1.25em 0; padding: 0 0 0.5625em 0; border: 0; } .quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; } .quoteblock .attribution { margin-top: -.25em; padding-bottom: 0.5625em; font-size: 0.8125em; color: #748590; } .quoteblock .attribution br { display: none; } .quoteblock .attribution cite { display: block; margin-bottom: 0.625em; } table thead th, table tfoot th { font-weight: bold; } table.tableblock.grid-all { border-collapse: separate; border-spacing: 1px; -webkit-border-radius: 6px; border-radius: 6px; border-top: 0 solid #dddddd; border-bottom: 0 solid #dddddd; } table.tableblock.frame-topbot, table.tableblock.frame-none { border-left: 0; border-right: 0; } table.tableblock.frame-sides, table.tableblock.frame-none { border-top: 0; border-bottom: 0; } table.tableblock td .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; } th.tableblock.halign-left, td.tableblock.halign-left { text-align: left; } th.tableblock.halign-right, td.tableblock.halign-right { text-align: right; } th.tableblock.halign-center, td.tableblock.halign-center { text-align: center; } th.tableblock.valign-top, td.tableblock.valign-top { vertical-align: top; } th.tableblock.valign-bottom, td.tableblock.valign-bottom { vertical-align: bottom; } th.tableblock.valign-middle, td.tableblock.valign-middle { vertical-align: middle; } tbody tr th { display: table-cell; line-height: 1.5; background: none; } tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #222222; font-weight: bold; } td > div.verse { white-space: pre; } ol { margin-left: 0.25em; } ul li ol { margin-left: 0; } dl dd { margin-left: 1.125em; } dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; } ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.625em; } ul.unstyled, ol.unnumbered, ul.checklist, ul.none { list-style-type: none; } ul.unstyled, ol.unnumbered, ul.checklist { margin-left: 0.625em; } ul.checklist li > p:first-child > i[class^="icon-check"]:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; } ul.checklist li > p:first-child > input[type="checkbox"]:first-child { position: relative; top: 1px; } ul.inline { margin: 0 auto 0.625em auto; margin-left: -1.375em; margin-right: 0; padding: 0; list-style: none; overflow: hidden; } ul.inline > li { list-style: none; float: left; margin-left: 1.375em; display: block; } ul.inline > li > * { display: block; } .unstyled dl dt { font-weight: normal; font-style: normal; } ol.arabic { list-style-type: decimal; } ol.decimal { list-style-type: decimal-leading-zero; } ol.loweralpha { list-style-type: lower-alpha; } ol.upperalpha { list-style-type: upper-alpha; } ol.lowerroman { list-style-type: lower-roman; } ol.upperroman { list-style-type: upper-roman; } ol.lowergreek { list-style-type: lower-greek; } .hdlist > table, .colist > table { border: 0; background: none; } .hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; } td.hdlist1 { padding-right: .75em; font-weight: bold; } td.hdlist1, td.hdlist2 { vertical-align: top; } .literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; } .colist > table tr > td:first-of-type { padding: 0 .75em; line-height: 1; } .colist > table tr > td:last-of-type { padding: 0.25em 0; } .qanda > ol > li > p > em:only-child { color: #373737; } .thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; } .imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; } .imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; } .imageblock > .title { margin-bottom: 0; } .imageblock.thumb, .imageblock.th { border-width: 6px; } .imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; } .image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; } .image.left { margin-right: 0.625em; } .image.right { margin-left: 0.625em; } a.image { text-decoration: none; } span.footnote, span.footnoteref { vertical-align: super; font-size: 0.875em; } span.footnote a, span.footnoteref a { text-decoration: none; } #footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; } #footnotes hr { width: 20%; min-width: 6.25em; margin: -.25em 0 .75em 0; border-width: 1px 0 0 0; } #footnotes .footnote { padding: 0 0.375em; line-height: 1.3; font-size: 0.875em; margin-left: 1.2em; text-indent: -1.2em; margin-bottom: .2em; } #footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; } #footnotes .footnote:last-of-type { margin-bottom: 0; } #content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; } .gist .file-data > table { border: none; background: #fff; width: 100%; margin-bottom: 0; } .gist .file-data > table td.line-data { width: 99%; } div.unbreakable { page-break-inside: avoid; } .big { font-size: larger; } .small { font-size: smaller; } .underline { text-decoration: underline; } .overline { text-decoration: overline; } .line-through { text-decoration: line-through; } .aqua { color: #00bfbf; } .aqua-background { background-color: #00fafa; } .black { color: black; } .black-background { background-color: black; } .blue { color: #0000bf; } .blue-background { background-color: #0000fa; } .fuchsia { color: #bf00bf; } .fuchsia-background { background-color: #fa00fa; } .gray { color: #606060; } .gray-background { background-color: #7d7d7d; } .green { color: #006000; } .green-background { background-color: #007d00; } .lime { color: #00bf00; } .lime-background { background-color: #00fa00; } .maroon { color: #600000; } .maroon-background { background-color: #7d0000; } .navy { color: #000060; } .navy-background { background-color: #00007d; } .olive { color: #606000; } .olive-background { background-color: #7d7d00; } .purple { color: #600060; } .purple-background { background-color: #7d007d; } .red { color: #bf0000; } .red-background { background-color: #fa0000; } .silver { color: #909090; } .silver-background { background-color: #bcbcbc; } .teal { color: #006060; } .teal-background { background-color: #007d7d; } .white { color: #bfbfbf; } .white-background { background-color: #fafafa; } .yellow { color: #bfbf00; } .yellow-background { background-color: #fafa00; } span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; } .admonitionblock td.icon [class^="icon-"]:before { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; } .admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #444444; color: #333333; } .admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; } .admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; } .admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; } .admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; } .conum { display: inline-block; color: white !important; background-color: black; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; width: 20px; height: 20px; font-size: 12px; font-weight: bold; line-height: 20px; font-family: Arial, sans-serif; font-style: normal; position: relative; top: -2px; letter-spacing: -1px; } .conum * { color: white !important; } .conum + b { display: none; } .conum:after { content: attr(data-value); } .conum:not([data-value]):empty { display: none; } .listingblock code { white-space: pre; overflow: auto; overflow-wrap: normal; /* needed for webkit browsers */ } #toc ul.sectlevel0 > li > a { font-style: normal; font-weight: bold; } h4 { color: #6c818f; } .literalblock > .content > pre, .listingblock > .content > pre { -webkit-border-radius: 6px; border-radius: 6px; margin-left: 2em; margin-right: 2em; } .admonitionblock { margin-left: 2em; margin-right: 2em; } .admonitionblock > table { border: 1px solid #609060; border-top-width: 1.5em; background-color: #e9ffe9; border-collapse: separate; -webkit-border-radius: 0; border-radius: 0; } .admonitionblock > table td.icon { padding-top: .5em; padding-bottom: .5em; } .admonitionblock > table td.content { padding: .5em 1em; color: black; font-size: .9em; border-left: none; } .sidebarblock { background-color: #e8ecef; border-color: #ccc; } .sidebarblock > .content > .title { color: #444444; } table.tableblock.grid-all { border-collapse: collapse; -webkit-border-radius: 0; border-radius: 0; } table.tableblock.grid-all th.tableblock, table.tableblock.grid-all td.tableblock { border-bottom: 1px solid #aaa; } #footer { background-color: #465158; padding: 2em; } #footer-text { color: #eee; font-size: 0.8em; text-align: center; } .tabs{position:relative;margin:40px auto;width:1024px;max-width:100%;overflow:hidden;padding-top:10px;margin-bottom:60px}.tabs input{position:absolute;z-index:1000;height:50px;left:0;top:0;opacity:0;-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=0)";filter:alpha(opacity=0);cursor:pointer;margin:0}.tabs input:hover+label{background:#e08f24}.tabs label{background:#e9ffe9;color:#1a1a1a;font-size:15px;line-height:50px;height:60px;position:relative;top:0;padding:0 20px;float:left;display:block;letter-spacing:1px;text-transform:uppercase;font-weight:bold;text-align:center;box-shadow:2px 0 2px rgba(0,0,0,0.1),-2px 0 2px rgba(0,0,0,0.1);box-sizing:border-box;-webkit-transition:all 150ms ease 0s;transition:all 150ms ease 0s}.tabs label:hover{cursor:pointer}.tabs label:after{content:'';background:#609060;position:absolute;bottom:-2px;left:0;width:100%;height:2px;display:block}.tabs-2 input{width:50%}.tabs-2 input.tab-selector-1{left:0%}.tabs-2 input.tab-selector-2{left:50%}.tabs-2 label{width:50%}.tabs-3 input{width:33.3333333333%}.tabs-3 input.tab-selector-1{left:0%}.tabs-3 input.tab-selector-2{left:33.3333333333%}.tabs-3 input.tab-selector-3{left:66.6666666667%}.tabs-3 label{width:33.3333333333%}.tabs-4 input{width:25%}.tabs-4 input.tab-selector-1{left:0%}.tabs-4 input.tab-selector-2{left:25%}.tabs-4 input.tab-selector-3{left:50%}.tabs-4 input.tab-selector-4{left:75%}.tabs-4 label{width:25%}.tabs-5 input{width:20%}.tabs-5 input.tab-selector-1{left:0%}.tabs-5 input.tab-selector-2{left:20%}.tabs-5 input.tab-selector-3{left:40%}.tabs-5 input.tab-selector-4{left:60%}.tabs-5 input.tab-selector-5{left:80%}.tabs-5 label{width:20%}.tabs-6 input{width:16.6666666667%}.tabs-6 input.tab-selector-1{left:0%}.tabs-6 input.tab-selector-2{left:16.6666666667%}.tabs-6 input.tab-selector-3{left:33.3333333333%}.tabs-6 input.tab-selector-4{left:50%}.tabs-6 input.tab-selector-5{left:66.6666666667%}.tabs-6 input.tab-selector-6{left:83.3333333333%}.tabs-6 label{width:16.6666666667%}.tabs-7 input{width:14.2857142857%}.tabs-7 input.tab-selector-1{left:0%}.tabs-7 input.tab-selector-2{left:14.2857142857%}.tabs-7 input.tab-selector-3{left:28.5714285714%}.tabs-7 input.tab-selector-4{left:42.8571428571%}.tabs-7 input.tab-selector-5{left:57.1428571429%}.tabs-7 input.tab-selector-6{left:71.4285714286%}.tabs-7 input.tab-selector-7{left:85.7142857143%}.tabs-7 label{width:14.2857142857%}.tabs label:first-of-type{z-index:4}.tab-label-2{z-index:4}.tab-label-3{z-index:3}.tab-label-4{z-index:2}.tabs input:checked+label{background:#609060;color:#fefefe;z-index:6}.clear-shadow{clear:both}.tabcontent{height:auto;width:100%;float:left;position:relative;z-index:5;background:#eee;top:-10px;box-sizing:border-box}.tabcontent>div{position:relative;float:left;width:0;height:0;box-sizing:border-box;top:0;left:0;z-index:1;opacity:0;background:#eee}.tabcontent .CodeRay{background-color:#fefefe}.tabs .tab-selector-1:checked ~ .tabcontent .tabcontent-1{z-index:100;-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=100)";filter:alpha(opacity=100);opacity:1;width:100%;height:auto;width:100%;height:auto;padding-top:30px}.tabs .tab-selector-2:checked ~ .tabcontent .tabcontent-2{z-index:100;-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=100)";filter:alpha(opacity=100);opacity:1;width:100%;height:auto;width:100%;height:auto;padding-top:30px}.tabs .tab-selector-3:checked ~ .tabcontent .tabcontent-3{z-index:100;-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=100)";filter:alpha(opacity=100);opacity:1;width:100%;height:auto;width:100%;height:auto;padding-top:30px}.tabs .tab-selector-4:checked ~ .tabcontent .tabcontent-4{z-index:100;-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=100)";filter:alpha(opacity=100);opacity:1;width:100%;height:auto;width:100%;height:auto;padding-top:30px}.tabs .tab-selector-5:checked ~ .tabcontent .tabcontent-5{z-index:100;-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=100)";filter:alpha(opacity=100);opacity:1;width:100%;height:auto;width:100%;height:auto;padding-top:30px}.tabs .tab-selector-6:checked ~ .tabcontent .tabcontent-6{z-index:100;-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=100)";filter:alpha(opacity=100);opacity:1;width:100%;height:auto;width:100%;height:auto;padding-top:30px}.tabs .tab-selector-7:checked ~ .tabcontent .tabcontent-7{z-index:100;-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=100)";filter:alpha(opacity=100);opacity:1;width:100%;height:auto;width:100%;height:auto;padding-top:30px} .invisible {color: rgba(0,0,0,0); font-size: 0;} </style> <style> /*! Stylesheet for CodeRay to loosely match GitHub themes | MIT License */ pre.CodeRay{background:#f7f7f8} .CodeRay .line-numbers{border-right:1px solid;opacity:.35;padding:0 .5em 0 0;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none} .CodeRay span.line-numbers{display:inline-block;margin-right:.75em} .CodeRay .line-numbers strong{color:#000} table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none} table.CodeRay td{vertical-align:top;line-height:inherit} table.CodeRay td.line-numbers{text-align:right} table.CodeRay td.code{padding:0 0 0 .75em} .CodeRay .debug{color:#fff!important;background:navy!important} .CodeRay .annotation{color:#007} .CodeRay .attribute-name{color:navy} .CodeRay .attribute-value{color:#700} .CodeRay .binary{color:#509} .CodeRay .comment{color:#998;font-style:italic} .CodeRay .char{color:#04d} .CodeRay .char .content{color:#04d} .CodeRay .char .delimiter{color:#039} .CodeRay .class{color:#458;font-weight:bold} .CodeRay .complex{color:#a08} .CodeRay .constant,.CodeRay .predefined-constant{color:teal} .CodeRay .color{color:#099} .CodeRay .class-variable{color:#369} .CodeRay .decorator{color:#b0b} .CodeRay .definition{color:#099} .CodeRay .delimiter{color:#000} .CodeRay .doc{color:#970} .CodeRay .doctype{color:#34b} .CodeRay .doc-string{color:#d42} .CodeRay .escape{color:#666} .CodeRay .entity{color:#800} .CodeRay .error{color:#808} .CodeRay .exception{color:inherit} .CodeRay .filename{color:#099} .CodeRay .function{color:#900;font-weight:bold} .CodeRay .global-variable{color:teal} .CodeRay .hex{color:#058} .CodeRay .integer,.CodeRay .float{color:#099} .CodeRay .include{color:#555} .CodeRay .inline{color:#000} .CodeRay .inline .inline{background:#ccc} .CodeRay .inline .inline .inline{background:#bbb} .CodeRay .inline .inline-delimiter{color:#d14} .CodeRay .inline-delimiter{color:#d14} .CodeRay .important{color:#555;font-weight:bold} .CodeRay .interpreted{color:#b2b} .CodeRay .instance-variable{color:teal} .CodeRay .label{color:#970} .CodeRay .local-variable{color:#963} .CodeRay .octal{color:#40e} .CodeRay .predefined{color:#369} .CodeRay .preprocessor{color:#579} .CodeRay .pseudo-class{color:#555} .CodeRay .directive{font-weight:bold} .CodeRay .type{font-weight:bold} .CodeRay .predefined-type{color:inherit} .CodeRay .reserved,.CodeRay .keyword{color:#000;font-weight:bold} .CodeRay .key{color:#808} .CodeRay .key .delimiter{color:#606} .CodeRay .key .char{color:#80f} .CodeRay .value{color:#088} .CodeRay .regexp .delimiter{color:#808} .CodeRay .regexp .content{color:#808} .CodeRay .regexp .modifier{color:#808} .CodeRay .regexp .char{color:#d14} .CodeRay .regexp .function{color:#404;font-weight:bold} .CodeRay .string{color:#d20} .CodeRay .string .string .string{background:#ffd0d0} .CodeRay .string .content{color:#d14} .CodeRay .string .char{color:#d14} .CodeRay .string .delimiter{color:#d14} .CodeRay .shell{color:#d14} .CodeRay .shell .delimiter{color:#d14} .CodeRay .symbol{color:#990073} .CodeRay .symbol .content{color:#a60} .CodeRay .symbol .delimiter{color:#630} .CodeRay .tag{color:teal} .CodeRay .tag-special{color:#d70} .CodeRay .variable{color:#036} .CodeRay .insert{background:#afa} .CodeRay .delete{background:#faa} .CodeRay .change{color:#aaf;background:#007} .CodeRay .head{color:#f8f;background:#505} .CodeRay .insert .insert{color:#080} .CodeRay .delete .delete{color:#800} .CodeRay .change .change{color:#66f} .CodeRay .head .head{color:#f4f} </style>   <script> var _paq = window._paq = window._paq || []; /* We explicitly disable cookie tracking to avoid privacy issues */ _paq.push(['disableCookies']); /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ _paq.push(['trackPageView']); _paq.push(['enableLinkTracking']); (function() { var u="https://analytics.apache.org/"; _paq.push(['setTrackerUrl', u+'matomo.php']); _paq.push(['setSiteId', '27']); var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); })(); </script>  </head> <body class="book toc2 toc-left"> <div id="header"> <div id="toc" class="toc2"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel0"> <li><a href="#_recipes">Recipes</a></li> <li><a href="#_traversal_recipes">Traversal Recipes</a> <ul class="sectlevel1"> <li><a href="#between-vertices">Between Vertices</a></li> <li><a href="#centrality">Centrality</a> <ul class="sectlevel2"> <li><a href="#degree-centrality">Degree Centrality</a></li> <li><a href="#betweeness-centrality">Betweeness Centrality</a></li> <li><a href="#closeness-centrality">Closeness Centrality</a></li> <li><a href="#eigenvector-centrality">Eigenvector Centrality</a></li> <li><a href="#pagerank-centrality">PageRank Centrality</a></li> </ul> </li> <li><a href="#collections">Collections</a></li> <li><a href="#connected-components">Connected Components</a> <ul class="sectlevel2"> <li><a href="#_small_graph_traversals">Small graph traversals</a></li> <li><a href="#_small_graph_scalability">Small graph scalability</a></li> <li><a href="#_large_graphs">Large graphs</a></li> </ul> </li> <li><a href="#cycle-detection">Cycle Detection</a></li> <li><a href="#duplicate-edge">Duplicate Edge Detection</a></li> <li><a href="#duplicate-vertex">Duplicate Vertex Detection</a></li> <li><a href="#edge-move">Moving an Edge</a></li> <li><a href="#element-existence">Element Existence</a></li> <li><a href="#if-then-based-grouping">If-Then Based Grouping</a></li> <li><a href="#looping">Looping</a> <ul class="sectlevel2"> <li><a href="#_conditional_looping_with_max_depth">Conditional Looping with Max Depth</a></li> <li><a href="#_emitting_loop_depth">Emitting Loop Depth</a></li> <li><a href="#_optional_loop_depth">Optional Loop Depth</a></li> </ul> </li> <li><a href="#operating-on-dropped-elements">Operating on Dropped Elements</a></li> <li><a href="#pagination">Pagination</a></li> <li><a href="#recommendation">Recommendation</a></li> <li><a href="#shortest-path">Shortest Path</a></li> <li><a href="#traversal-induced-values">Traversal Induced Values</a></li> <li><a href="#tree">Tree</a> <ul class="sectlevel2"> <li><a href="#_lowest_common_ancestor">Lowest Common Ancestor</a></li> <li><a href="#_maximum_depth">Maximum Depth</a></li> <li><a href="#_time_based_indexing">Time-based Indexing</a></li> </ul> </li> <li><a href="#olap-spark-yarn">OLAP traversals with Spark on YARN</a> <ul class="sectlevel2"> <li><a href="#_approach">Approach</a></li> <li><a href="#_prerequisites">Prerequisites</a></li> <li><a href="#_running_the_job">Running the job</a></li> <li><a href="#_explanation">Explanation</a></li> <li><a href="#_additional_configuration_options">Additional configuration options</a></li> </ul> </li> </ul> </li> <li><a href="#_anti_patterns">Anti-Patterns</a> <ul class="sectlevel1"> <li><a href="#long-traversals">Long Traversals</a></li> <li><a href="#unspecified-keys-and-labels">Unspecified Keys and Labels</a></li> <li><a href="#unnecessary-steps">Unnecessary Steps</a></li> <li><a href="#unspecified-label-in-global-vertex-lookup">Unspecified Label in Global Vertex lookup</a></li> <li><a href="#steps-instead-of-tokens">Steps Instead of Tokens</a></li> <li><a href="#_has_and_traversal_arguments">has() and Traversal Arguments</a></li> </ul> </li> <li><a href="#_implementation_recipes">Implementation Recipes</a> <ul class="sectlevel1"> <li><a href="#style-guide">Style Guide</a></li> <li><a href="#traversal-component-reuse">Traversal Component Reuse</a></li> </ul> </li> <li><a href="#contributing">How to Contribute a Recipe</a></li> <li><a href="#_appendix">Appendix</a></li> </ul> </div> </div> <div id="content"> <div id="preamble"> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <a class="image" href="https://tinkerpop.apache.org"><img src="../images/apache-tinkerpop-logo.png" alt="apache tinkerpop logo" width="500"></a> </div> </div> <div class="paragraph"> 3.7.3 </div> </div> </div> <h1 id="_recipes" class="sect0">Recipes</h1> <div class="openblock partintro"> <div class="content"> <div class="paragraph"> <img src="../images/gremlin-chef.png" alt="gremlin chef" width="120"> All programming languages tend to have <a href="https://en.wikipedia.org/wiki/Software_design_pattern">patterns of usage</a> for commonly occurring problems. Gremlin is not different in that respect. There are many commonly occurring traversal themes that have general applicability to any graph. Gremlin Recipes present these common traversal patterns and methods of usage that will provide some basic building blocks for virtually any graph in any domain. </div> <div class="paragraph"> Recipes assume general familiarity with Gremlin and the Apache TinkerPop™ stack. Be sure to have read the <a href="https://tinkerpop.apache.org/docs/3.7.3/tutorials/getting-started">Getting Started</a> tutorial and the <a href="https://tinkerpop.apache.org/docs/3.7.3/tutorials/the-gremlin-console/">The Gremlin Console</a> tutorial. </div> </div> </div> <h1 id="_traversal_recipes" class="sect0">Traversal Recipes</h1> <div class="sect1"> <h2 id="between-vertices">Between Vertices</h2> <div class="sectionbody"> <div class="paragraph"> It is quite common to have a situation where there are two particular vertices of a graph and a need to execute some traversal on the paths found between them. Consider the following examples using the modern toy graph: </div> <section class="tabs tabs-2"> <input id="tab-1729796703-1" type="radio" name="radio-set-1729796703-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796703-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796703-2" type="radio" name="radio-set-1729796703-1" class="tab-selector-2" /> <label for="tab-1729796703-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(1).bothE() //// (1) ==>e[9][1-created->3] ==>e[7][1-knows->2] ==>e[8][1-knows->4] gremlin> g.V(1).bothE().where(otherV().hasId(2)) //// (2) ==>e[7][1-knows->2] gremlin> v1 = g.V(1).next();[] gremlin> v2 = g.V(2).next();[] gremlin> g.V(v1).bothE().where(otherV().is(v2)) //// (3) ==>e[7][1-knows->2] gremlin> g.V(v1).outE().where(inV().is(v2)) //// (4) ==>e[7][1-knows->2] gremlin> g.V(1).outE().where(inV().has(id, within(2,3))) //// (5) ==>e[9][1-created->3] ==>e[7][1-knows->2] gremlin> g.V(1).out().where(__.in().hasId(6)) //// (6) ==>v[3]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(1).bothE() //// (1) g.V(1).bothE().where(otherV().hasId(2)) //// (2) v1 = g.V(1).next();[] v2 = g.V(2).next();[] g.V(v1).bothE().where(otherV().is(v2)) //// (3) g.V(v1).outE().where(inV().is(v2)) //// (4) g.V(1).outE().where(inV().has(id, within(2,3))) //// (5) g.V(1).out().where(__.in().hasId(6)) //6</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> There are three edges from the vertex with the identifier of "1". </li> <li> Filter those three edges using the <code>where()</code>-step using the identifier of the vertex returned by <code>otherV()</code> to ensure it matches on the vertex of concern, which is the one with an identifier of "2". </li> <li> Note that the same traversal will work if there are actual <code>Vertex</code> instances rather than just vertex identifiers. </li> <li> The vertex with identifier "1" has all outgoing edges, so it would also be acceptable to use the directional steps of <code>outE()</code> and <code>inV()</code> since the schema allows it. </li> <li> There is also no problem with filtering the terminating side of the traversal on multiple vertices, in this case, vertices with identifiers "2" and "3". </li> <li> There’s no reason why the same pattern of exclusion used for edges with <code>where()</code> can’t work for a vertex between two vertices. </li> </ol> </div> <div class="paragraph"> The basic pattern of using <code>where()</code>-step to find the "other" known vertex can be applied in far more complex scenarios. For one such example, consider the following traversal that finds all the paths between a group of defined vertices: </div> <section class="tabs tabs-2"> <input id="tab-1729796703-3" type="radio" name="radio-set-1729796703-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796703-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796703-4" type="radio" name="radio-set-1729796703-3" class="tab-selector-2" /> <label for="tab-1729796703-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> ids = [2,4,6].toArray() ==>2 ==>4 ==>6 gremlin> g.V(ids).as("a"). repeat(bothE().otherV().simplePath()).times(5).emit(hasId(within(ids))).as("b"). filter(select(last,"a","b").by(id).where("a", lt("b"))). path().by().by(label) ==>[v[2],knows,v[1],knows,v[4]] ==>[v[2],knows,v[1],created,v[3],created,v[4]] ==>[v[2],knows,v[1],created,v[3],created,v[6]] ==>[v[2],knows,v[1],knows,v[4],created,v[3],created,v[6]] ==>[v[4],created,v[3],created,v[6]] ==>[v[4],knows,v[1],created,v[3],created,v[6]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">ids = [2,4,6].toArray() g.V(ids).as("a"). repeat(bothE().otherV().simplePath()).times(5).emit(hasId(within(ids))).as("b"). filter(select(last,"a","b").by(id).where("a", lt("b"))). path().by().by(label)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> For another example, consider the following schema: </div> <div class="paragraph"> <img src="../images/recipe-job-schema.png" alt="recipe job schema" width="750"> </div> <div class="paragraph"> Assume that the goal is to find information about a known job and a known person. Specifically, the idea would be to extract the known job, the company that created the job, the date it was created by the company and whether or not the known person completed an application. </div> <section class="tabs tabs-2"> <input id="tab-1729796703-5" type="radio" name="radio-set-1729796703-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796703-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796703-6" type="radio" name="radio-set-1729796703-5" class="tab-selector-2" /> <label for="tab-1729796703-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV("person").property("name", "bob").as("bob"). addV("person").property("name", "stephen").as("stephen"). addV("company").property("name", "Blueprints, Inc").as("blueprints"). addV("company").property("name", "Rexster, LLC").as("rexster"). addV("job").property("name", "job1").as("blueprintsJob1"). addV("job").property("name", "job2").as("blueprintsJob2"). addV("job").property("name", "job3").as("blueprintsJob3"). addV("job").property("name", "job4").as("rexsterJob1"). addV("application").property("name", "application1").as("appBob1"). addV("application").property("name", "application2").as("appBob2"). addV("application").property("name", "application3").as("appStephen1"). addV("application").property("name", "application4").as("appStephen2"). addE("completes").from("bob").to("appBob1"). addE("completes").from("bob").to("appBob2"). addE("completes").from("stephen").to("appStephen1"). addE("completes").from("stephen").to("appStephen2"). addE("appliesTo").from("appBob1").to("blueprintsJob1"). addE("appliesTo").from("appBob2").to("blueprintsJob2"). addE("appliesTo").from("appStephen1").to("rexsterJob1"). addE("appliesTo").from("appStephen2").to("blueprintsJob3"). addE("created").from("blueprints").to("blueprintsJob1").property("creationDate", "12/20/2015"). addE("created").from("blueprints").to("blueprintsJob2").property("creationDate", "12/15/2015"). addE("created").from("blueprints").to("blueprintsJob3").property("creationDate", "12/16/2015"). addE("created").from("rexster").to("rexsterJob1").property("creationDate", "12/18/2015").iterate() gremlin> vBlueprintsJob1 = g.V().has("job", "name", "job1").next() ==>v[8] gremlin> vRexsterJob1 = g.V().has("job", "name", "job4").next() ==>v[14] gremlin> vStephen = g.V().has("person", "name", "stephen").next() ==>v[2] gremlin> vBob = g.V().has("person", "name", "bob").next() ==>v[0] gremlin> g.V(vRexsterJob1).as('job'). inE('created').as('created'). outV().as('company'). select('job'). coalesce(__.in('appliesTo').where(__.in('completes').is(vStephen)), constant(false)).as('application'). select('job', 'company', 'created', 'application'). by().by().by('creationDate').by() ==>[job:v[14],company:v[6],created:12/18/2015,application:v[20]] gremlin> g.V(vRexsterJob1, vBlueprintsJob1).as('job'). inE('created').as('created'). outV().as('company'). select('job'). coalesce(__.in('appliesTo').where(__.in('completes').is(vBob)), constant(false)).as('application'). select('job', 'company', 'created', 'application'). by().by().by('creationDate').by() ==>[job:v[14],company:v[6],created:12/18/2015,application:false] ==>[job:v[8],company:v[4],created:12/20/2015,application:v[16]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV("person").property("name", "bob").as("bob"). addV("person").property("name", "stephen").as("stephen"). addV("company").property("name", "Blueprints, Inc").as("blueprints"). addV("company").property("name", "Rexster, LLC").as("rexster"). addV("job").property("name", "job1").as("blueprintsJob1"). addV("job").property("name", "job2").as("blueprintsJob2"). addV("job").property("name", "job3").as("blueprintsJob3"). addV("job").property("name", "job4").as("rexsterJob1"). addV("application").property("name", "application1").as("appBob1"). addV("application").property("name", "application2").as("appBob2"). addV("application").property("name", "application3").as("appStephen1"). addV("application").property("name", "application4").as("appStephen2"). addE("completes").from("bob").to("appBob1"). addE("completes").from("bob").to("appBob2"). addE("completes").from("stephen").to("appStephen1"). addE("completes").from("stephen").to("appStephen2"). addE("appliesTo").from("appBob1").to("blueprintsJob1"). addE("appliesTo").from("appBob2").to("blueprintsJob2"). addE("appliesTo").from("appStephen1").to("rexsterJob1"). addE("appliesTo").from("appStephen2").to("blueprintsJob3"). addE("created").from("blueprints").to("blueprintsJob1").property("creationDate", "12/20/2015"). addE("created").from("blueprints").to("blueprintsJob2").property("creationDate", "12/15/2015"). addE("created").from("blueprints").to("blueprintsJob3").property("creationDate", "12/16/2015"). addE("created").from("rexster").to("rexsterJob1").property("creationDate", "12/18/2015").iterate() vBlueprintsJob1 = g.V().has("job", "name", "job1").next() vRexsterJob1 = g.V().has("job", "name", "job4").next() vStephen = g.V().has("person", "name", "stephen").next() vBob = g.V().has("person", "name", "bob").next() g.V(vRexsterJob1).as('job'). inE('created').as('created'). outV().as('company'). select('job'). coalesce(__.in('appliesTo').where(__.in('completes').is(vStephen)), constant(false)).as('application'). select('job', 'company', 'created', 'application'). by().by().by('creationDate').by() g.V(vRexsterJob1, vBlueprintsJob1).as('job'). inE('created').as('created'). outV().as('company'). select('job'). coalesce(__.in('appliesTo').where(__.in('completes').is(vBob)), constant(false)).as('application'). select('job', 'company', 'created', 'application'). by().by().by('creationDate').by()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> While the traversals above are more complex, the pattern for finding "things" between two vertices is largely the same. Note the use of the <code>where()</code>-step to terminate the traversers for a specific user. It is embedded in a <code>coalesce()</code> step to handle situations where the specified user did not complete an application for the specified job and will return <code>false</code> in those cases. </div> </div> </div> <div class="sect1"> <h2 id="centrality">Centrality</h2> <div class="sectionbody"> <div class="paragraph"> There are many measures of <a href="https://en.wikipedia.org/wiki/Centrality">centrality</a> which are meant to help identify the most important vertices in a graph. As these measures are common in graph theory, this section attempts to demonstrate how some of these different indicators can be calculated using Gremlin. </div> <div class="sect2"> <h3 id="degree-centrality">Degree Centrality</h3> <div class="paragraph"> <a href="https://en.wikipedia.org/wiki/Centrality#Degree_centrality">Degree centrality</a> is a measure of the number of edges associated to each vertex. The following examples use the modern toy graph: </div> <section class="tabs tabs-2"> <input id="tab-1729796714-1" type="radio" name="radio-set-1729796714-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796714-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796714-2" type="radio" name="radio-set-1729796714-1" class="tab-selector-2" /> <label for="tab-1729796714-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().group().by().by(bothE().count()) //// (1) ==>[v[1]:3,v[2]:1,v[3]:3,v[4]:3,v[5]:1,v[6]:1] gremlin> g.V().group().by().by(inE().count()) //// (2) ==>[v[1]:0,v[2]:1,v[3]:3,v[4]:1,v[5]:1,v[6]:0] gremlin> g.V().group().by().by(outE().count()) //// (3) ==>[v[1]:3,v[2]:0,v[3]:0,v[4]:2,v[5]:0,v[6]:1] gremlin> g.V().project("v","degree").by().by(bothE().count()) //// (4) ==>[v:v[1],degree:3] ==>[v:v[2],degree:1] ==>[v:v[3],degree:3] ==>[v:v[4],degree:3] ==>[v:v[5],degree:1] ==>[v:v[6],degree:1] gremlin> g.V().project("v","degree").by().by(bothE().count()). //// (5) order().by("degree", desc). limit(4) ==>[v:v[1],degree:3] ==>[v:v[3],degree:3] ==>[v:v[4],degree:3] ==>[v:v[2],degree:1]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().group().by().by(bothE().count()) //// (1) g.V().group().by().by(inE().count()) //// (2) g.V().group().by().by(outE().count()) //// (3) g.V().project("v","degree").by().by(bothE().count()) //// (4) g.V().project("v","degree").by().by(bothE().count()). //// (5) order().by("degree", desc). limit(4)</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Calculation of degree centrality which counts all incident edges on each vertex to include those that are both incoming and outgoing. </li> <li> Calculation of in-degree centrality which only counts incoming edges to a vertex. </li> <li> Calculation of out-degree centrality which only counts outgoing edges from a vertex. </li> <li> The previous examples all produce a single <code>Map</code> as their output. While that is a desirable output, producing a stream of <code>Map</code> objects can allow some greater flexibility. </li> <li> For example, use of a stream enables use of an ordered limit that can be executed in a distributed fashion in OLAP traversals. </li> </ol> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> The <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#group-step">group</a> step takes up to two separate <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#by-step">by</a> modulators. The first <code>by()</code> tells <code>group()</code> what the key in the resulting <code>Map</code> will be (i.e. the value to group on). In the above examples, the <code>by()</code> is empty and as a result, the grouping will be on the incoming <code>Vertex</code> object itself. The second <code>by()</code> is the value to be stored in the <code>Map</code> for each key. </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="betweeness-centrality">Betweeness Centrality</h3> <div class="paragraph"> <a href="https://en.wikipedia.org/wiki/Betweenness_centrality">Betweeness centrality</a> is a measure of the number of times a vertex is found between the <a href="#shortest-path">shortest path</a> of each vertex pair in a graph. Consider the following graph for demonstration purposes: </div> <div class="paragraph"> <img src="../images/betweeness-example.png" alt="betweeness example" width="600"> </div> <section class="tabs tabs-2"> <input id="tab-1729796714-3" type="radio" name="radio-set-1729796714-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796714-3" class="tab-label-1">console (groovy )</label> <input id="tab-1729796714-4" type="radio" name="radio-set-1729796714-3" class="tab-selector-2" /> <label for="tab-1729796714-4" class="tab-label-2">groovy </label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id,'A').as('a'). addV().property(id,'B').as('b'). addV().property(id,'C').as('c'). addV().property(id,'D').as('d'). addV().property(id,'E').as('e'). addV().property(id,'F').as('f'). addE('next').from('a').to('b'). addE('next').from('b').to('c'). addE('next').from('b').to('d'). addE('next').from('c').to('e'). addE('next').from('d').to('e'). addE('next').from('e').to('f').iterate() gremlin> g.V().as("v"). //// (1) repeat(both().simplePath().as("v")).emit(). //// (2) filter(project("x","y","z").by(select(first, "v")). //// (3) by(select(last, "v")). by(select(all, "v").count(local)).as("triple"). coalesce(select("x","y").as("a"). //// (4) select("triples").unfold().as("t"). select("x","y").where(eq("a")). select("t"), aggregate(local,"triples")). //// (5) select("z").as("length"). select("triple").select("z").where(eq("length"))). //// (6) select(all, "v").unfold(). //// (7) groupCount().next() //// (8) ==>v[A]=14 ==>v[B]=28 ==>v[C]=20 ==>v[D]=20 ==>v[E]=28 ==>v[F]=14</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id,'A').as('a'). addV().property(id,'B').as('b'). addV().property(id,'C').as('c'). addV().property(id,'D').as('d'). addV().property(id,'E').as('e'). addV().property(id,'F').as('f'). addE('next').from('a').to('b'). addE('next').from('b').to('c'). addE('next').from('b').to('d'). addE('next').from('c').to('e'). addE('next').from('d').to('e'). addE('next').from('e').to('f').iterate() g.V().as("v"). //// (1) repeat(both().simplePath().as("v")).emit(). //// (2) filter(project("x","y","z").by(select(first, "v")). //// (3) by(select(last, "v")). by(select(all, "v").count(local)).as("triple"). coalesce(select("x","y").as("a"). //// (4) select("triples").unfold().as("t"). select("x","y").where(eq("a")). select("t"), aggregate(local,"triples")). //// (5) select("z").as("length"). select("triple").select("z").where(eq("length"))). //// (6) select(all, "v").unfold(). //// (7) groupCount().next() //8</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Starting from each vertex in the graph… </li> <li> …traverse on both - incoming and outgoing - edges, avoiding <a href="#cycle-detection">cyclic paths</a>. </li> <li> Create a triple consisting of the first vertex, the last vertex and the length of the path between them. </li> <li> Determine whether a path between those two vertices was already found. </li> <li> If this is the first path between the two vertices, store the triple in an internal collection named "triples". </li> <li> Keep only those paths between a pair of vertices that have the same length as the first path that was found between them. </li> <li> Select all shortest paths and unfold them. </li> <li> Count the number of occurrences of each vertex, which is ultimately its betweeness score. </li> </ol> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <div class="title">Warning</div> </td> <td class="content"> Since the betweeness centrality algorithm requires the shortest path between any pair of vertices in the graph, its practical applications are very limited. It’s recommended to use this algorithm only on small subgraphs (graphs like the <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#grateful-dead">Grateful Dead graph</a> with only 808 vertices and 8049 edges already require a massive amount of compute resources to determine the shortest paths between all vertex pairs). </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="closeness-centrality">Closeness Centrality</h3> <div class="paragraph"> <a href="https://en.wikipedia.org/wiki/Centrality">Closeness centrality</a> is a measure of the distance of one vertex to all other reachable vertices in the graph. The following examples use the modern toy graph: </div> <section class="tabs tabs-2"> <input id="tab-1729796714-5" type="radio" name="radio-set-1729796714-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796714-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796714-6" type="radio" name="radio-set-1729796714-5" class="tab-selector-2" /> <label for="tab-1729796714-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSack(1f).V().as("v"). //// (1) repeat(both().simplePath().as("v")).emit(). //// (2) filter(project("x","y","z").by(select(first, "v")). //// (3) by(select(last, "v")). by(select(all, "v").count(local)).as("triple"). coalesce(select("x","y").as("a"). //// (4) select("triples").unfold().as("t"). select("x","y").where(eq("a")). select("t"), aggregate(local,"triples")). //// (5) select("z").as("length"). select("triple").select("z").where(eq("length"))). //// (6) group().by(select(first, "v")). //// (7) by(select(all, "v").count(local).sack(div).sack().sum()).next() ==>v[1]=2.1666666666666665 ==>v[2]=1.6666666666666665 ==>v[3]=2.1666666666666665 ==>v[4]=2.1666666666666665 ==>v[5]=1.6666666666666665 ==>v[6]=1.6666666666666665</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSack(1f).V().as("v"). //// (1) repeat(both().simplePath().as("v")).emit(). //// (2) filter(project("x","y","z").by(select(first, "v")). //// (3) by(select(last, "v")). by(select(all, "v").count(local)).as("triple"). coalesce(select("x","y").as("a"). //// (4) select("triples").unfold().as("t"). select("x","y").where(eq("a")). select("t"), aggregate(local,"triples")). //// (5) select("z").as("length"). select("triple").select("z").where(eq("length"))). //// (6) group().by(select(first, "v")). //// (7) by(select(all, "v").count(local).sack(div).sack().sum()).next()</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Defines a Gremlin <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#sack-step">sack</a> with a value of one. </li> <li> Traverses on both - incoming and outgoing - edges, avoiding <a href="#cycle-detection">cyclic paths</a>. </li> <li> Create a triple consisting of the first vertex, the last vertex and the length of the path between them. </li> <li> Determine whether a path between those two vertices was already found. </li> <li> If this is the first path between the two vertices, store the triple in an internal collection named "triples". </li> <li> Keep only those paths between a pair of vertices that have the same length as the first path that was found between them. </li> <li> For each vertex divide 1 by the product of the lengths of all shortest paths that start with this particular vertex. </li> </ol> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <div class="title">Warning</div> </td> <td class="content"> Since the closeness centrality algorithm requires the shortest path between any pair of vertices in the graph, its practical applications are very limited. It’s recommended to use this algorithm only on small subgraphs (graphs like the <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#grateful-dead">Grateful Dead graph</a> with only 808 vertices and 8049 edges already require a massive amount of compute resources to determine the shortest paths between all vertex pairs). </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="eigenvector-centrality">Eigenvector Centrality</h3> <div class="paragraph"> A calculation of <a href="https://en.wikipedia.org/wiki/Centrality#Eigenvector_centrality">eigenvector centrality</a> uses the relative importance of adjacent vertices to help determine their centrality. In other words, unlike <a href="#degree-centrality">degree centrality</a> the vertex with the greatest number of incident edges does not necessarily give it the highest rank. Consider the following example using the Grateful Dead graph: </div> <section class="tabs tabs-2"> <input id="tab-1729796714-7" type="radio" name="radio-set-1729796714-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796714-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796714-8" type="radio" name="radio-set-1729796714-7" class="tab-selector-2" /> <label for="tab-1729796714-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.io('data/grateful-dead.xml').read().iterate() gremlin> g.V().repeat(groupCount('m').by('name').out()).times(5).cap('m'). //// (1) order(local).by(values, desc).limit(local, 10).next() //// (2) ==>PLAYING IN THE BAND=8758598 ==>ME AND MY UNCLE=8214246 ==>JACK STRAW=8173882 ==>EL PASO=7666994 ==>TRUCKING=7643494 ==>PROMISED LAND=7339027 ==>CHINA CAT SUNFLOWER=7322213 ==>CUMBERLAND BLUES=6730838 ==>RAMBLE ON ROSE=6676667 ==>LOOKS LIKE RAIN=6674121 gremlin> g.V().repeat(groupCount('m').by('name').out().timeLimit(100)).times(5).cap('m'). //// (3) order(local).by(values, desc).limit(local, 10).next() ==>PLAYING IN THE BAND=8758598 ==>ME AND MY UNCLE=8214246 ==>JACK STRAW=8173882 ==>EL PASO=7666994 ==>TRUCKING=7643494 ==>PROMISED LAND=7339027 ==>CHINA CAT SUNFLOWER=7322213 ==>CUMBERLAND BLUES=6730838 ==>RAMBLE ON ROSE=6676667 ==>LOOKS LIKE RAIN=6674121</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.io('data/grateful-dead.xml').read().iterate() g.V().repeat(groupCount('m').by('name').out()).times(5).cap('m'). //// (1) order(local).by(values, desc).limit(local, 10).next() //// (2) g.V().repeat(groupCount('m').by('name').out().timeLimit(100)).times(5).cap('m'). //// (3) order(local).by(values, desc).limit(local, 10).next()</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The traversal iterates through each vertex in the graph and for each one repeatedly group counts each vertex that passes through using the vertex as the key. The <code>Map</code> of this group count is stored in a variable named "m". The <code>out()</code> traversal is repeated thirty times or until the paths are exhausted. Five iterations should provide enough time to converge on a solution. Calling <code>cap('m')</code> at the end simply extracts the <code>Map</code> side-effect stored in "m". </li> <li> The entries in the <code>Map</code> are then iterated and sorted with the top ten most central vertices presented as output. </li> <li> The previous examples can be expanded on a little bit by including a <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#timelimit-step">time limit</a>. The <code>timeLimit()</code> prevents the traversal from taking longer than one hundred milliseconds to execute (the previous example takes considerably longer than that). While the answer provided with the <code>timeLimit()</code> is not the absolute ranking, it does provide a relative ranking that closely matches the absolute one. The use of <code>timeLimit()</code> in certain algorithms (e.g. recommendations) can shorten the time required to get a reasonable and usable result. </li> </ol> </div> </div> <div class="sect2"> <h3 id="pagerank-centrality">PageRank Centrality</h3> <div class="paragraph"> While not technically a recipe, it’s worth noting here in the "Centrality Section" that <a href="https://en.wikipedia.org/wiki/PageRank">PageRank</a> centrality can be calculated with Gremlin with the <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#pagerank-step">pageRank()</a>-step which is designed to work with <code>GraphComputer</code> (OLAP) based traversals. </div> <section class="tabs tabs-2"> <input id="tab-1729796714-9" type="radio" name="radio-set-1729796714-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796714-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796714-10" type="radio" name="radio-set-1729796714-9" class="tab-selector-2" /> <label for="tab-1729796714-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g = traversal().withEmbedded(graph).withComputer() ==>graphtraversalsource[tinkergraph[vertices:6 edges:6], graphcomputer] gremlin> g.V().pageRank().with(PageRank.propertyName,'pageRank').values('pageRank') ==>0.30472009079122503 ==>0.17579889899708237 ==>0.11375510357865543 ==>0.11375510357865543 ==>0.14598540152719108 ==>0.14598540152719108</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g = traversal().withEmbedded(graph).withComputer() g.V().pageRank().with(PageRank.propertyName,'pageRank').values('pageRank')</code></pre> </div> </div> </div> </div> </section> </div> </div> </div> <div class="sect1"> <h2 id="collections">Collections</h2> <div class="sectionbody"> <div class="paragraph"> <img src="../images/gremlin-collections.png" alt="gremlin collections" width="400"> </div> <div class="paragraph"> Lists and maps form the basis for much of the processing in Gremlin traversals. They are core to how side-effects are typically held and how results are generally produced. Being able to pick them apart and reformat them is sometimes required. This need to shape the data within a traversal may arise both at the <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#terminal-steps">terminal step</a> of the traversal (technically just prior to the terminal step) or in the middle of a traversal. Considering the former, a transformation just prior to iteration will get the result into the form required by the application which would remove the need for additional application level manipulation. Moreover, a transformation at this stage may reduce the size of the payload being returned which could be useful in remote applications. Examining the latter, there may be times where a <code>List</code> or <code>Map</code> requires some mid-traversal transformation so as to continue with the general logic of the traversal itself. For example, a traversal at some point might produce a <code>Map</code> of <code>List</code> objects where the lists contain vertices, where each <code>List</code> might need to be sorted by some criteria and then the top item for each extracted to become the basis for the continued traversal. Executing transformations for either of these types of situations can be made possible with the patterns described in this section. </div> <div class="paragraph"> The appearance of a <code>List</code> as a traverser in Gremlin usually arises as a result of a <code>fold()</code> operation, but may also appear by way of some side-effect steps like <code>aggregate()</code>: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-1" type="radio" name="radio-set-1729796726-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-2" type="radio" name="radio-set-1729796726-1" class="tab-selector-2" /> <label for="tab-1729796726-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().fold() ==>[v[1],v[2],v[3],v[4],v[5],v[6]] gremlin> g.V().aggregate(local, 'a').cap('a') ==>[v[1],v[2],v[3],v[4],v[5],v[6]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().fold() g.V().aggregate(local, 'a').cap('a')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> It is worth noting that while a <code>Path</code> is not technically a <code>List</code> it does present like one and can be manipulated in similar fashion to lists: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-3" type="radio" name="radio-set-1729796726-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-4" type="radio" name="radio-set-1729796726-3" class="tab-selector-2" /> <label for="tab-1729796726-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().out().out().path() ==>[v[1],v[4],v[5]] ==>[v[1],v[4],v[3]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().out().out().path()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> These examples are obviously trivial and there are other ways that a traverser might end up in a <code>List</code> form, but, at this moment, the point here is to focus less on how to get a <code>List</code> and more on how to manipulate one within the Gremlin language. The examples going forward will also be similarly contrived insofar as producing a usable <code>List</code> to manipulate. Bear in mind that it may be quite possible to get the same end results of these examples using more direct means than what is demonstrated. </div> <div class="paragraph"> It may seem simple, but the most obvious choice to modifying what is in a list is to simply <code>unfold()</code> the <code>List</code>: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-5" type="radio" name="radio-set-1729796726-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-6" type="radio" name="radio-set-1729796726-5" class="tab-selector-2" /> <label for="tab-1729796726-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().fold().unfold().values('name') ==>marko ==>vadas ==>lop ==>josh ==>ripple ==>peter gremlin> g.V().aggregate(local,'a').cap('a').unfold().values('name') ==>marko ==>vadas ==>lop ==>josh ==>ripple ==>peter</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().fold().unfold().values('name') g.V().aggregate(local,'a').cap('a').unfold().values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The above examples show that <code>unfold()</code> works quite well when you don’t want to preserve the <code>List</code> structure of the traverser as it just flattens <code>List</code> traversers to the traversal stream. The above examples only have one <code>List</code> as a result, but consider what happens when there is more than one: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-7" type="radio" name="radio-set-1729796726-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-8" type="radio" name="radio-set-1729796726-7" class="tab-selector-2" /> <label for="tab-1729796726-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().union(fold(),fold()) ==>[v[1],v[2],v[3],v[4],v[5],v[6]] ==>[v[1],v[2],v[3],v[4],v[5],v[6]] gremlin> g.V().union(fold(),fold()).unfold().values('name') ==>marko ==>marko ==>vadas ==>vadas ==>lop ==>lop ==>josh ==>josh ==>ripple ==>ripple ==>peter ==>peter</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().union(fold(),fold()) g.V().union(fold(),fold()).unfold().values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The two separate <code>List</code> traversers are flattened to a single traversal stream and all the results are mixed together. While this approach may be acceptable, there are many cases where it might not be so. To preserve the individual structure of the <code>List</code> traversers "locally" <code>unfold()</code> the lists to transform them: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-9" type="radio" name="radio-set-1729796726-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-10" type="radio" name="radio-set-1729796726-9" class="tab-selector-2" /> <label for="tab-1729796726-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(). union(fold(),fold()). local(unfold().values('name').fold()) ==>[marko,vadas,lop,josh,ripple,peter] ==>[marko,vadas,lop,josh,ripple,peter]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(). union(fold(),fold()). local(unfold().values('name').fold())</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The call to <code>local()</code> executes its anonymous sub-traversal over each individual <code>List</code> iterator and as the sub-traversal ends with a <code>fold()</code>-step, the results are reduced back into a <code>List</code> to preserve the original structure, thus maintaining two traverser results. </div> <div class="paragraph"> This pattern for unfolding and folding <code>List</code> traversers ends up having other applications: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-11" type="radio" name="radio-set-1729796726-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-12" type="radio" name="radio-set-1729796726-11" class="tab-selector-2" /> <label for="tab-1729796726-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().union(limit(3).fold(),tail(3).fold()) //// (1) ==>[v[1],v[2],v[3]] ==>[v[4],v[5],v[6]] gremlin> g.V().union(limit(3).fold(),tail(3).fold()). local(unfold(). //// (2) order(). by(bothE().count(),desc). limit(1). fold()) ==>[v[1]] ==>[v[4]] gremlin> g.V().union(limit(3).fold(),tail(3).fold()). //// (3) local(unfold(). has('age',gte(29)). values('age'). mean()) ==>29.0 ==>33.5</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().union(limit(3).fold(),tail(3).fold()) //// (1) g.V().union(limit(3).fold(),tail(3).fold()). local(unfold(). //// (2) order(). by(bothE().count(),desc). limit(1). fold()) g.V().union(limit(3).fold(),tail(3).fold()). //// (3) local(unfold(). has('age',gte(29)). values('age'). mean())</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The output consists of two <code>List</code> traversers. </li> <li> For each <code>List</code> of vertices, order them by their number of edges, and choose the first one which will be the one with the highest degree (i.e. number of edges). By ending with <code>fold()</code> the <code>List</code> traverser structure is preserved thus returning two <code>List</code> objects. Consider this a method for choosing a "max" or a highly ranked vertex. In this case the rank was determined by the number of edges, but it could have just as easily been determined by a vertex property, edge property, a calculated value, etc. - one simply needs to alter the <code>by()</code>-step modulator to <code>order()</code>. </li> <li> For each <code>List</code> of vertices, filter that <code>List</code> to only include vertices that have an "age" property with a value greater than or equal to "29" and then average the results of each list. More generally, consider how this approach performs some kind of reducing calculation on each <code>List</code> traverser. In this case, an average was calculated, but it might also have been a <code>sum()</code>, <code>count()</code> or similar operation that reduced the list to a single calculated value. </li> </ol> </div> <div class="paragraph"> So far, this section has focused on what to do with a <code>List</code> traverser once there is one present and there have been fairly contrived examples for how to produce one in the first place. The use of <code>fold()</code> has been used most frequently at this point to achieve list creation and that step should be recalled whenever there is a need to reduce some traversal stream to an actual <code>List</code>. Of course, it may become necessary to more manually construct a <code>List</code>, especially in cases where the expected output of the traversal is composed of one or more ordered results in the form of a <code>List</code>. For example, consider the following three traversals: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-13" type="radio" name="radio-set-1729796726-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-14" type="radio" name="radio-set-1729796726-13" class="tab-selector-2" /> <label for="tab-1729796726-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko').values('age') //// (1) ==>29 gremlin> g.V().has('name','marko'). //// (2) repeat(out()). until(has('lang','java')). path(). by('name') ==>[marko,lop] ==>[marko,josh,ripple] ==>[marko,josh,lop] gremlin> g.V().has('name','marko'). //// (3) repeat(outE().inV()). until(has('lang','java')). path(). local(unfold(). has('weight'). values('weight'). mean()) ==>0.4 ==>1.0 ==>0.7</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko').values('age') //// (1) g.V().has('name','marko'). //// (2) repeat(out()). until(has('lang','java')). path(). by('name') g.V().has('name','marko'). //// (3) repeat(outE().inV()). until(has('lang','java')). path(). local(unfold(). has('weight'). values('weight'). mean())</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Get the age of "marko" </li> <li> get the "name" values of the vertices in the collected paths that traverse out from "marko" to any vertex with the "lang" of "java". </li> <li> Get the average of the "weight" values of edges in the collected paths that traverse out from "marko" to any vertex with the "lang" of "java". Note the use of the earlier defined pattern that used <code>local()</code> in conjunction with <code>unfold()</code>. In this case it filters out vertices from the <code>Path</code> as they are not relevant as the concern is only with the "weight" property on the edges. </li> </ol> </div> <div class="paragraph"> For purposes of this example, the three traversals above happen to represent three pieces of data that are required by an application. It is plain to note that all of the above traversals hold a similar pattern that starts with "getting 'marko'" and, in the case of the latter two, traversing on outgoing edges away from him and collecting data from that path. Ideally, all three of these traversals should execute as one to prevent having to submit three separate traversals, thus incurring additional query execution costs for what amounts to be largely the same underlying data but with different transformations applied. The goal here would be to return the results of this data as a <code>List</code> with three results (i.e. triple) that could then be submitted once by the application. The following example demonstrates the use of <code>aggregate()</code> to aid in construction of this <code>List</code>: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-15" type="radio" name="radio-set-1729796726-15" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-15" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-16" type="radio" name="radio-set-1729796726-15" class="tab-selector-2" /> <label for="tab-1729796726-16" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko').as('v'). //// (1) aggregate(local,'a'). //// (2) by('age'). repeat(outE().as('e').inV().as('v')). //// (3) until(has('lang','java')). aggregate('b'). //// (4) by(select(all,'v').unfold().values('name').fold()). aggregate('c'). //// (5) by(select(all,'e').unfold().values('weight').mean()). fold(). //// (6) aggregate(local,'a'). //// (7) by(cap('b')). aggregate(local,'a'). //// (8) by(cap('c')). cap('a') ==>[29,[[marko,lop],[marko,josh,ripple],[marko,josh,lop]],[0.4,1.0,0.7]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko').as('v'). //// (1) aggregate(local,'a'). //// (2) by('age'). repeat(outE().as('e').inV().as('v')). //// (3) until(has('lang','java')). aggregate('b'). //// (4) by(select(all,'v').unfold().values('name').fold()). aggregate('c'). //// (5) by(select(all,'e').unfold().values('weight').mean()). fold(). //// (6) aggregate(local,'a'). //// (7) by(cap('b')). aggregate(local,'a'). //// (8) by(cap('c')). cap('a')</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Get the "marko" vertex and label that step as "v". </li> <li> Store the first "age" of "marko" as the first item in the <code>List</code> called "a", which will ultimately be the result. </li> <li> Execute the traversal away from "marko" and continue to traverse on outgoing edges until the vertex has the value of "java" for the "lang" property. Note the labels of "e" and "v". Note that "e" will contain a <code>List</code> of all of the edges that have been traversed and "v" will contain a <code>List</code> of all the vertices that have been traversed. </li> <li> The incoming traverser to <code>aggregate('b')</code> are vertices that terminate the <code>repeat()</code> (i.e. those with the "lang" of "java"). Note however that the <code>by()</code> modulator overrides that traverser completely by starting a fresh stream of the list of vertices in "v". Those vertices are unfolded to retrieve the name property from each and then are reduced with <code>fold()</code> back into a list to be stored in the side-effected named "b". </li> <li> A similar use of <code>aggregate()</code> as the previous step, though this one turns "e" into a stream of edges to calculate the <code>mean()</code> to store in a <code>List</code> called "c". Note that <code>aggregate()</code> (short form for <code>aggregate(global)</code>) was used here instead of <code>aggregate(local)</code>, as the former is an eager collection of the elements in the stream (<code>aggregate(local)</code> is lazy) and will force the traversal to be iterated up to that point before moving forward. Without that eager collection, "v" and "e" would not contain the complete information required for the production of "b" and "c". </li> <li> Adding <code>fold()</code>-step here is a bit of a trick. To see the trick, copy and paste all lines of Gremlin up to but not including this <code>fold()</code>-step and run them against the "modern" graph. The output is three vertices and if the <code>profile()</code>-step was added one would also see that the traversal contained three traversers. These three traversers with a vertex in each one were produced from the <code>repeat()</code>-step (i.e. those vertices that had the "lang" of "java" when traversing away from "marko"). The <code>aggregate()</code>-steps are side-effects and just allow the traversers to pass through them unchanged. The <code>fold()</code> obviously converts those three traversers to a single <code>List</code> to make one traverser with a <code>List</code> inside. That means that the remaining steps following the <code>fold()</code> will only be executed one time each instead of three, which, as will be shown, is critical to the proper result. </li> <li> The single traverser with the <code>List</code> of three vertices in it passes to <code>aggregate(local)</code>. The <code>by()</code> modulator presents an override telling Gremlin to ignore the <code>List</code> of three vertices and simply grab the "b" side effect created earlier and stick that into "a" as part of the result. The <code>List</code> with three vertices passes out unchanged as <code>aggregate(local)</code> is a side-effect step. </li> <li> Again, the single traverser with the <code>List</code> of three vertices passes to <code>aggregate(local)</code> and again, the <code>by()</code> modulator presents an override to include "c" into the result. </li> </ol> </div> <div class="paragraph"> All of the above code and explanation show that <code>aggregate()</code> can be used to construct <code>List</code> objects as side-effects which can then be used as a result. Note that <code>aggregate()</code> can take a <code>Scope</code>, should it make sense that lazy <code>List</code> creation is not acceptable with respect to the nature of the traversal. An interesting sub-pattern that emerges here is that the <code>by()</code>-step can modulate its step to completely override the current traverser and ignore its contents for purpose of that step. This ability to override a traverser acts as a powerful and flexible tool as it means that each traverser can effectively become a completely different object as determined by a sub-traversal. </div> <div class="paragraph"> Another interesting method for <code>List</code> creation was demonstrated a bit earlier but not examined in detail - the use of <code>union()</code>. It was shown earlier in the following context where it helped create a <code>List</code> of two lists of three vertices each: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-17" type="radio" name="radio-set-1729796726-17" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-17" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-18" type="radio" name="radio-set-1729796726-17" class="tab-selector-2" /> <label for="tab-1729796726-18" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().union(limit(3).fold(),tail(3).fold()) ==>[v[1],v[2],v[3]] ==>[v[4],v[5],v[6]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().union(limit(3).fold(),tail(3).fold())</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> By folding the results of <code>union()</code>, it becomes possible to essentially construct lists with arbitrary traversal results. </div> <section class="tabs tabs-2"> <input id="tab-1729796726-19" type="radio" name="radio-set-1729796726-19" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-19" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-20" type="radio" name="radio-set-1729796726-19" class="tab-selector-2" /> <label for="tab-1729796726-20" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(). local(union(identity(), //// (1) bothE().count()). fold()) ==>[v[1],3] ==>[v[2],1] ==>[v[3],3] ==>[v[4],3] ==>[v[5],1] ==>[v[6],1] gremlin> g.V(). aggregate(local, 'x'). by(union(select('x').count(local), //// (2) identity(), bothE().count()). fold()). cap('x') ==>[[0,v[1],3],[1,v[2],1],[2,v[3],3],[3,v[4],3],[4,v[5],1],[5,v[6],1]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(). local(union(identity(), //// (1) bothE().count()). fold()) g.V(). aggregate(local, 'x'). by(union(select('x').count(local), //// (2) identity(), bothE().count()). fold()). cap('x')</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> For each vertex, create a "pair" (i.e. a <code>List</code> of two objects) of the vertex itself and its edge count. </li> <li> For each vertex, create a "triple" (i.e. a <code>List</code> of three objects) of the index of the vertex (starting at zero), the vertex itself and its edge count. </li> </ol> </div> <div class="paragraph"> The pattern here is to use <code>union()</code> in conjunction with <code>fold()</code>. As explained earlier, the <code>fold()</code> operation reduces the stream from <code>union()</code> to a single <code>List</code> that is then fed forward to the next step in the traversal. </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> TinkerPop 3.4.4 introduced <code>elementMap()</code>-step which essentially replaces much of the transformations described below that are applied to the results of <code>valueMap()</code>-step. While the direct use of <code>elementMap()</code> eliminates the need for the transformation, the explanations below are still edifying and worth examining. </td> </tr> </table> </div> <div class="paragraph"> Now that <code>List</code> patterns have been explained, there can now be some attention on <code>Map</code>. One of the most common ways to end up with a <code>Map</code> is with <code>valueMap()</code>: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-21" type="radio" name="radio-set-1729796726-21" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-21" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-22" type="radio" name="radio-set-1729796726-21" class="tab-selector-2" /> <label for="tab-1729796726-22" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko').valueMap('name','age') ==>[name:[marko],age:[29]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko').valueMap('name','age')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The problem is that unless the graph is making use of multi-properties, there is little need to have the value of each property stored as a <code>List</code>. One way to unwrap this value from the list is to avoid having it there in the first place by avoiding use of <code>valueMap()</code>: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-23" type="radio" name="radio-set-1729796726-23" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-23" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-24" type="radio" name="radio-set-1729796726-23" class="tab-selector-2" /> <label for="tab-1729796726-24" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko'). local(properties('name','age'). group().by(key()).by(value())) ==>[name:marko,age:29]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko'). local(properties('name','age'). group().by(key()).by(value()))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Interestingly, it’s worth looking at how to process the output of <code>valueMap()</code> to attain this output as the approach is generally applicable to processing any <code>Map</code> instances with any sorts of values: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-25" type="radio" name="radio-set-1729796726-25" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-25" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-26" type="radio" name="radio-set-1729796726-25" class="tab-selector-2" /> <label for="tab-1729796726-26" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko'). valueMap('name','age'). unfold(). group(). by(keys). by(select(values).unfold()) ==>[name:marko,age:29]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko'). valueMap('name','age'). unfold(). group(). by(keys). by(select(values).unfold())</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The code above, basically deconstructs then reconstructs the <code>Map</code>. The key to the pattern is to first <code>unfold()</code> the <code>Map</code> into its key and value entries. Then for each key and value produce a new <code>Map</code> using <code>group()</code> where the key for that map is the key of the entry (those are obviously unique as you picked them out of the <code>valueMap()</code>) and the value is simply the <code>unfold()</code> of the list of values in each entry. Recall that the <code>select(values).unfold()</code> only returns one value (i.e. the first) not only because there is only one, but also because <code>by()</code> will only call <code>next()</code> on that sub-traversal (it does not iterate the entire thing). </div> <div class="paragraph"> Generally speaking, a <code>Map</code> constructed as part of <code>group()</code> or <code>project()</code> will already be in the form required as the <code>by()</code> modulators would be written in such a fashion as to produce that final output. It would be unnecessary to deconstruct/reconstruct it. Be certain that there isn’t a way to re-write the <code>group()</code> or <code>project()</code> to get the desired output before taking this approach. </div> <div class="paragraph"> In the following case, <code>project()</code> is used to create a <code>Map</code> that does not meet this requirement as it contains some unavoidable extraneous keys in the output <code>Map</code>: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-27" type="radio" name="radio-set-1729796726-27" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-27" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-28" type="radio" name="radio-set-1729796726-27" class="tab-selector-2" /> <label for="tab-1729796726-28" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(). project('name','age','lang'). by('name'). by(coalesce(values('age'),constant('n/a'))). by(coalesce(values('lang'),constant('n/a'))) ==>[name:marko,age:29,lang:n/a] ==>[name:vadas,age:27,lang:n/a] ==>[name:lop,age:n/a,lang:java] ==>[name:josh,age:32,lang:n/a] ==>[name:ripple,age:n/a,lang:java] ==>[name:peter,age:35,lang:n/a]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(). project('name','age','lang'). by('name'). by(coalesce(values('age'),constant('n/a'))). by(coalesce(values('lang'),constant('n/a')))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The use of <code>coalesce()</code> works around the problem where "age" and "lang" are not necessarily property keys present on every single vertex in the traversal stream. When the "age" or "lang" are not present, the constant of "n/a" is supplied. While this may be an acceptable output, it is possible to shape the <code>Map</code> to be "nicer": </div> <section class="tabs tabs-2"> <input id="tab-1729796726-29" type="radio" name="radio-set-1729796726-29" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-29" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-30" type="radio" name="radio-set-1729796726-29" class="tab-selector-2" /> <label for="tab-1729796726-30" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(). project('name','age','lang'). by('name'). by(coalesce(values('age'),constant('n/a'))). by(coalesce(values('lang'),constant('n/a'))). local(unfold(). filter(select(values).is(P.neq('n/a'))). group(). by(keys). by(values)) ==>[name:[marko],age:[29]] ==>[name:[vadas],age:[27]] ==>[name:[lop],lang:[java]] ==>[name:[josh],age:[32]] ==>[name:[ripple],lang:[java]] ==>[name:[peter],age:[35]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(). project('name','age','lang'). by('name'). by(coalesce(values('age'),constant('n/a'))). by(coalesce(values('lang'),constant('n/a'))). local(unfold(). filter(select(values).is(P.neq('n/a'))). group(). by(keys). by(values))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The additional steps above <code>unfold()</code> the <code>Map</code> to key-value entries and filter the values for "n/a" and remove them prior to reconstructing the <code>Map</code> with the method shown earlier. To go a step further, apply the pattern presented earlier to flatten <code>List</code> values within a <code>Map</code>: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-31" type="radio" name="radio-set-1729796726-31" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-31" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-32" type="radio" name="radio-set-1729796726-31" class="tab-selector-2" /> <label for="tab-1729796726-32" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(). project('name','age','lang'). by('name'). by(coalesce(values('age'),constant('n/a'))). by(coalesce(values('lang'),constant('n/a'))). local(unfold(). filter(select(values).is(P.neq('n/a'))). group(). by(keys). by(select(values).unfold())) ==>[name:marko,age:29] ==>[name:vadas,age:27] ==>[name:lop,lang:java] ==>[name:josh,age:32] ==>[name:ripple,lang:java] ==>[name:peter,age:35]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(). project('name','age','lang'). by('name'). by(coalesce(values('age'),constant('n/a'))). by(coalesce(values('lang'),constant('n/a'))). local(unfold(). filter(select(values).is(P.neq('n/a'))). group(). by(keys). by(select(values).unfold()))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> As there may be a desire to remove entries from a <code>Map</code>, there may also be the need to add keys to a <code>Map</code>. The pattern here involves the use of a <code>union()</code> that returns the <code>Map</code> instances which can be flattened to entries and then reconstructed as a new <code>Map</code> that has been merged together: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-33" type="radio" name="radio-set-1729796726-33" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-33" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-34" type="radio" name="radio-set-1729796726-33" class="tab-selector-2" /> <label for="tab-1729796726-34" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(). has('name','marko'). union(project('degree'). //// (1) by(bothE().count()), valueMap().with(WithOptions.tokens)). unfold(). //// (2) group(). by(keys). by(select(values).unfold()) ==>[degree:3,name:marko,id:1,label:person,age:29]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(). has('name','marko'). union(project('degree'). //// (1) by(bothE().count()), valueMap().with(WithOptions.tokens)). unfold(). //// (2) group(). by(keys). by(select(values).unfold())</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The <code>valueMap().with(WithOptions.tokens)</code> of a <code>Vertex</code> can be extended with the "degree" of the <code>Vertex</code> by performing a <code>union()</code> of the two traversals that produce that output (both produce <code>Map</code> objects). Recall that <code>valueMap().with(WithOptions.tokens)</code> is replaced by <code>elementMap()</code> in 3.4.4 - this examples continues with the "old" form for demonstration purposes. </li> <li> The <code>unfold()</code>-step is used to decompose the <code>Map</code> objects into key/value entries that are then constructed back into a single new <code>Map</code> given the patterns shown earlier. The <code>Map</code> objects of both traversals in the <code>union()</code> are essentially merged together. </li> </ol> </div> <div class="paragraph"> When using this pattern, it is important to recognize that if there are non-unique keys produced by the traversals supplied to <code>union()</code>, they will overwrite one another given the final <code>by()</code> modulator above. If changed to <code>by(select(values).unfold().fold())</code> they will merge to produce a <code>List</code> of values. Of course, that change will bring a <code>List</code> back for all the values of the new <code>Map</code>. With some added logic the <code>Map</code> values can be flattened out of <code>List</code> instances when necessary: </div> <section class="tabs tabs-2"> <input id="tab-1729796726-35" type="radio" name="radio-set-1729796726-35" class="tab-selector-1" checked="checked" /> <label for="tab-1729796726-35" class="tab-label-1">console (groovy)</label> <input id="tab-1729796726-36" type="radio" name="radio-set-1729796726-35" class="tab-selector-2" /> <label for="tab-1729796726-36" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(). has('name','marko'). union(valueMap().with(WithOptions.tokens), project('age'). by(constant(100))). unfold(). group(). by(keys). by(select(values). unfold(). fold(). choose(count(local).is(eq(1)), unfold())) ==>[name:marko,id:1,label:person,age:[29,100]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(). has('name','marko'). union(valueMap().with(WithOptions.tokens), project('age'). by(constant(100))). unfold(). group(). by(keys). by(select(values). unfold(). fold(). choose(count(local).is(eq(1)), unfold()))</code></pre> </div> </div> </div> </div> </section> </div> </div> <div class="sect1"> <h2 id="connected-components">Connected Components</h2> <div class="sectionbody"> <div class="paragraph"> Gremlin can be used to find <a href="https://en.wikipedia.org/wiki/Connected_component_(graph_theory)">connected components</a> in a graph. In a directed graph like in TinkerPop, components can be weakly or strongly connected. This recipe is restricted to finding <a href="https://en.wikipedia.org/wiki/Directed_graph#Directed_graph_connectivity">weakly connected components</a>, in which the direction of edges is not taken into account. </div> <div class="paragraph"> Depending on the size of the graph, three solution regimes can be discriminated: </div> <div class="olist arabic"> <ol class="arabic"> <li> Small graphs that fit in the memory of a single machine </li> <li> Medium-sized graphs backed by storage for which an OLTP linear scan is still feasible. This regime is left to third party TinkerPop implementations, since TinkerPop itself has no storage-backed reference implementations. The idea is that component membership is stored in the graph, rather than in memory. </li> <li> Large graphs requiring an approach with <code>HadoopGraph</code> and <code>SparkGraphComputer</code> to yield results in a reasonable time. </li> </ol> </div> <div class="paragraph"> These regimes are discussed separately using the following graph with three weakly connected components: </div> <div class="paragraph"> <img src="../images/connected-components.png" alt="connected components" width="600"> </div> <section class="tabs tabs-2"> <input id="tab-1729796742-1" type="radio" name="radio-set-1729796742-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796742-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796742-2" type="radio" name="radio-set-1729796742-1" class="tab-selector-2" /> <label for="tab-1729796742-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id, "A").as("a"). addV().property(id, "B").as("b"). addV().property(id, "C").as("c"). addV().property(id, "D").as("d"). addV().property(id, "E").as("e"). addV().property(id, "F"). addE("link").from("a").to("b"). addE("link").from("b").to("c"). addE("link").from("d").to("e").iterate()</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id, "A").as("a"). addV().property(id, "B").as("b"). addV().property(id, "C").as("c"). addV().property(id, "D").as("d"). addV().property(id, "E").as("e"). addV().property(id, "F"). addE("link").from("a").to("b"). addE("link").from("b").to("c"). addE("link").from("d").to("e").iterate()</code></pre> </div> </div> </div> </div> </section> <div class="sect2"> <h3 id="_small_graph_traversals">Small graph traversals</h3> <div class="paragraph"> Connected components in a small graph can be determined with either an OLTP traversal or the OLAP <code>connectedComponent()</code>-step. The <code>connectedComponent()</code>-step is available as of TinkerPop 3.4.0 and is described in more detail in the <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#connectedcomponent-step">Reference Documentation</a>. The traversal looks like: </div> <section class="tabs tabs-2"> <input id="tab-1729796742-3" type="radio" name="radio-set-1729796742-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796742-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796742-4" type="radio" name="radio-set-1729796742-3" class="tab-selector-2" /> <label for="tab-1729796742-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withComputer().V().connectedComponent(). group().by(ConnectedComponent.component). select(values).unfold() ==>[v[E],v[D]] ==>[v[C],v[B],v[A]] ==>[v[F]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withComputer().V().connectedComponent(). group().by(ConnectedComponent.component). select(values).unfold()</code></pre> </div> </div> </div> </div> </section> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> The <code>component</code> option passed to <code>by()</code> is statically imported from <code>ConnectedComponent</code> and refers to the default property key within which the result of the algorithm is stored. </td> </tr> </table> </div> <div class="paragraph"> A straightforward way to detect the various subgraphs with an OLTP traversal is to do this: </div> <section class="tabs tabs-2"> <input id="tab-1729796742-5" type="radio" name="radio-set-1729796742-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796742-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796742-6" type="radio" name="radio-set-1729796742-5" class="tab-selector-2" /> <label for="tab-1729796742-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().emit(cyclicPath().or().not(both())). //// (1) repeat(__.where(without('a')).aggregate(local,'a').both()).until(cyclicPath()). //// (2) group().by(path().unfold().limit(1)). //// (3) by(path().unfold().dedup().fold()). //// (4) select(values).unfold() //// (5) ==>[v[A],v[B],v[C]] ==>[v[D],v[E]] ==>[v[F]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().emit(cyclicPath().or().not(both())). //// (1) repeat(__.where(without('a')).aggregate(local,'a').both()).until(cyclicPath()). //// (2) group().by(path().unfold().limit(1)). //// (3) by(path().unfold().dedup().fold()). //// (4) select(values).unfold() //5</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The initial emit() step allows for output of isolated vertices, in addition to the discovery of components as described in (2). </li> <li> The entire component to which the first returned vertex belongs, is visited. To allow for components of any structure, a repeat loop is applied that only stops for a particular branch of the component when it detects a cyclic path. Collection <code>'a'</code> is used to keep track of visited vertices, for both subtraversals within a component and new traversals resulting from the <code>g.V()</code> linear scan. </li> <li> While <code>'a'</code> nicely keeps track of vertices already visited, the actual components need to be extracted from the path information. The <code>path().unfold().limit(1)</code> closure provides the starting vertex of surviving traversers, which can be used to group the components. </li> <li> This clause collects the unique vertices from all paths with the same starting vertex, thus from the same weak component. </li> <li> The values of the groupby map contain the lists of vertices making up the requested components. </li> </ol> </div> </div> <div class="sect2"> <h3 id="_small_graph_scalability">Small graph scalability</h3> <div class="paragraph"> The scalability of the OLTP traversal and the <code>connectedComponent()</code>-step for in-memory graphs is shown in the figures below. </div> <div id="cc-scale-size" class="imageblock"> <div class="content"> <img src="../images/cc-scale-size.png" alt="cc scale size" width="600"> </div> <div class="title">Figure 1. Run times for finding connected components in a randomly generated graph with 10 components of equal size and with an edge/vertex ratio of 6</div> </div> <div class="paragraph"> In general, the <code>connectedComponent()</code>-step is almost a factor two faster than the OLTP traversal. Only, for very small graphs the overhead of running the ConnectedComponentVertexProgram is larger than that of the OLTP traversal. The vertex program works by having interconnected vertices exchange id’s and store the lowest id until no vertex receives a lower id. This algorithm is commonly applied in <a href="https://en.wikipedia.org/wiki/Bulk_synchronous_parallel">bulk synchronous parallel</a> systems, e.g. in <a href="https://spark.apache.org/graphx">Apache Spark GraphX</a>. Overhead for the vertex program arises because it has to run as many cycles as the largest length of the shortest paths between any two vertices in a component of the graph. In every cycle each vertex has to be checked for being "halted". Overhead of the OLTP traversal consists of each traverser having to carry complete path information. For pure depth-first-search or breadth-first-search implementations, connected-component algotithms should scale as O(V+E). For the traversals in the figure above this is almost the case. </div> <div id="cc-scale-ratio" class="imageblock"> <div class="content"> <img src="../images/cc-scale-ratio.png" alt="cc scale ratio" width="600"> </div> <div class="title">Figure 2. Run times for finding connected components in a randomly generated graph with 10 components, each consisting of 6400 vertices</div> </div> <div class="paragraph"> The random graphs used for the scalability tests can be modulated with the edge/vertex ratio. For small ratios the components generated are more lint-like and harder to process by the <code>connectedComponent()</code>-step. For high ratios the components are more mesh-like and the ConnectedComponentVertexProgram needs few cycles to process the graph. These characteristics show clearly from the graph. Indeed, for a given number of vertices, the run time of the <code>connectedComponent()</code>-step does not depend on the number of edges, but rather on the maximum shortest path length in the graph. </div> </div> <div class="sect2"> <h3 id="_large_graphs">Large graphs</h3> <div class="paragraph"> Large graphs in TinkerPop require distributed processing by <code>SparkGraphComputer</code> to get results in a reasonable time (OLAP approach). This means that the graph must be available as <code>HadoopGraph</code> (third party TinkerPop implementations often allow to make a graph available as an <code>HadoopGraph</code> by providing an Hadoop <code>InputFormat</code>). Running the <code>connectedComponent()</code>-step on an <code>HadoopGraph</code> works the same as for a small graph, provided that <code>SparkGraphComputer</code> is specified as the graph computer, either with the <code>gremlin.hadoop.defaultGraphComputer</code> property or as part of the <code>withComputer()</code>-step. </div> <div class="paragraph"> Scalability of the the <code>connectedComponent()</code>-step with <code>SparkGraphComputer</code> is high, but note that: </div> <div class="ulist"> <ul> <li> The graph should fit in the memory of the Spark cluster to allow the VertexProgram to run its cycles without spilling intermediate results to disk and loosing most of the gains from the distributed processing. </li> <li> As discussed for small graphs, the BSP algorithm does not play well with graphs having a large shortest path between any pair of vertices. Overcoming this limitation is still a <a href="http://www.vldb.org/pvldb/vol7/p1821-yan.pdf">subject of academic research</a>. </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="cycle-detection">Cycle Detection</h2> <div class="sectionbody"> <div class="paragraph"> A cycle occurs in a graph where a path loops back on itself to the originating vertex. For example, in the graph depicted below Gremlin could be use to detect the cycle among vertices <code>A-B-C</code>. </div> <div class="paragraph"> <img src="../images/graph-cycle.png" alt="graph cycle" width="250"> </div> <section class="tabs tabs-2"> <input id="tab-1729796752-1" type="radio" name="radio-set-1729796752-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796752-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796752-2" type="radio" name="radio-set-1729796752-1" class="tab-selector-2" /> <label for="tab-1729796752-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id,'a').as('a'). addV().property(id,'b').as('b'). addV().property(id,'c').as('c'). addV().property(id,'d').as('d'). addE('knows').from('a').to('b'). addE('knows').from('b').to('c'). addE('knows').from('c').to('a'). addE('knows').from('a').to('d'). addE('knows').from('c').to('d').iterate() gremlin> g.V().as('a').repeat(out().simplePath()).times(2). where(out().as('a')).path() //// (1) ==>[v[a],v[b],v[c]] ==>[v[b],v[c],v[a]] ==>[v[c],v[a],v[b]] gremlin> g.V().as('a').repeat(out().simplePath()).times(2). where(out().as('a')).path(). dedup().by(unfold().order().by(id).dedup().fold()) //// (2) ==>[v[a],v[b],v[c]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id,'a').as('a'). addV().property(id,'b').as('b'). addV().property(id,'c').as('c'). addV().property(id,'d').as('d'). addE('knows').from('a').to('b'). addE('knows').from('b').to('c'). addE('knows').from('c').to('a'). addE('knows').from('a').to('d'). addE('knows').from('c').to('d').iterate() g.V().as('a').repeat(out().simplePath()).times(2). where(out().as('a')).path() //// (1) g.V().as('a').repeat(out().simplePath()).times(2). where(out().as('a')).path(). dedup().by(unfold().order().by(id).dedup().fold()) //2</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Gremlin starts its traversal from a vertex labeled "a" and traverses <code>out()</code> from each vertex filtering on the <code>simplePath</code>, which removes paths with repeated objects. The steps going <code>out()</code> are repeated twice as in this case the length of the cycle is known to be three and there is no need to exceed that. The traversal filters with a <code>where()</code> to see only return paths that end with where it started at "a". </li> <li> The previous query returned the <code>A-B-C</code> cycle, but it returned three paths which were all technically the same cycle. It returned three, because there was one for each vertex that started the cycle (i.e. one for <code>A</code>, one for <code>B</code> and one for <code>C</code>). This next line introduce deduplication to only return unique cycles. </li> </ol> </div> <div class="paragraph"> The above case assumed that the need was to only detect cycles over a path length of three. It also respected the directionality of the edges by only considering outgoing ones. </div> <div class="paragraph"> Also note that the traversal above won’t detect self-loops (vertices directly connected to themselves). To do so, you would need to <code>.emit()</code> a Traverser before the repeat()-loop. </div> <section class="tabs tabs-2"> <input id="tab-1729796752-3" type="radio" name="radio-set-1729796752-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796752-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796752-4" type="radio" name="radio-set-1729796752-3" class="tab-selector-2" /> <label for="tab-1729796752-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id,'a').as('a'). addV().property(id,'b').as('b'). addV().property(id,'c').as('c'). addV().property(id,'d').as('d'). addE('knows').from('a').to('b'). addE('knows').from('b').to('c'). addE('knows').from('c').to('a'). addE('knows').from('a').to('d'). addE('knows').from('c').to('d'). addE('self').from('a').to('a').iterate() gremlin> g.V().as('a'). emit(). repeat(outE().inV().simplePath()). times(2). outE().inV().where(eq('a')). path(). by(id). by(label) ==>[a,self,a] ==>[a,knows,b,knows,c,knows,a] ==>[b,knows,c,knows,a,knows,b] ==>[c,knows,a,knows,b,knows,c]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id,'a').as('a'). addV().property(id,'b').as('b'). addV().property(id,'c').as('c'). addV().property(id,'d').as('d'). addE('knows').from('a').to('b'). addE('knows').from('b').to('c'). addE('knows').from('c').to('a'). addE('knows').from('a').to('d'). addE('knows').from('c').to('d'). addE('self').from('a').to('a').iterate() g.V().as('a'). emit(). repeat(outE().inV().simplePath()). times(2). outE().inV().where(eq('a')). path(). by(id). by(label)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> What would need to change to detect cycles of arbitrary length over both incoming and outgoing edges, in the modern graph? </div> <section class="tabs tabs-2"> <input id="tab-1729796752-5" type="radio" name="radio-set-1729796752-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796752-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796752-6" type="radio" name="radio-set-1729796752-5" class="tab-selector-2" /> <label for="tab-1729796752-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().as('a').repeat(both().simplePath()).emit(loops().is(gt(1))). both().where(eq('a')).path(). dedup().by(unfold().order().by(id).dedup().fold()) ==>[v[1],v[3],v[4],v[1]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().as('a').repeat(both().simplePath()).emit(loops().is(gt(1))). both().where(eq('a')).path(). dedup().by(unfold().order().by(id).dedup().fold())</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> An interesting type of cycle is known as the Eulerian circuit which is a path taken in a graph where each edge is visited once and the path starts and ends with the same vertex. Consider the following graph, representative of an imaginary but geographically similar <a href="https://en.wikipedia.org/wiki/Seven_Bridges_of_K%C3%B6nigsberg">Königsberg</a> that happens to have an eighth bridge (the diagram depicts edge direction but direction won’t be considered in the traversal): </div> <div class="paragraph"> <img src="../images/eulerian-circuit.png" alt="eulerian circuit" width="500"> </div> <div class="paragraph"> Gremlin can detect if such a cycle exists with: </div> <section class="tabs tabs-2"> <input id="tab-1729796752-7" type="radio" name="radio-set-1729796752-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796752-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796752-8" type="radio" name="radio-set-1729796752-7" class="tab-selector-2" /> <label for="tab-1729796752-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id, 'blue').as('b'). addV().property(id, 'orange').as('o'). addV().property(id, 'red').as('r'). addV().property(id, 'green').as('g'). addE('bridge').from('g').to('b'). addE('bridge').from('g').to('o'). addE('bridge').from('g').to('r'). addE('bridge').from('g').to('r'). addE('bridge').from('o').to('b'). addE('bridge').from('o').to('b'). addE('bridge').from('o').to('r'). addE('bridge').from('o').to('r').iterate() gremlin> g.V().sideEffect(outE("bridge").aggregate("bridges")).barrier(). //// (1) repeat(bothE(). //// (2) or(__.not(select('e')), __.not(filter(__.as('x').select(all, 'e').unfold(). //// (3) where(eq('x'))))).as('e'). otherV()). until(select(all, 'e').count(local).as("c"). //// (4) select("bridges").count(local).where(eq("c"))).hasNext() ==>true</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id, 'blue').as('b'). addV().property(id, 'orange').as('o'). addV().property(id, 'red').as('r'). addV().property(id, 'green').as('g'). addE('bridge').from('g').to('b'). addE('bridge').from('g').to('o'). addE('bridge').from('g').to('r'). addE('bridge').from('g').to('r'). addE('bridge').from('o').to('b'). addE('bridge').from('o').to('b'). addE('bridge').from('o').to('r'). addE('bridge').from('o').to('r').iterate() g.V().sideEffect(outE("bridge").aggregate("bridges")).barrier(). //// (1) repeat(bothE(). //// (2) or(__.not(select('e')), __.not(filter(__.as('x').select(all, 'e').unfold(). //// (3) where(eq('x'))))).as('e'). otherV()). until(select(all, 'e').count(local).as("c"). //// (4) select("bridges").count(local).where(eq("c"))).hasNext()</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Gather all the edges in a "bridges" side effect. </li> <li> As mentioned earlier with the diagram, directionality is ignored as the traversal uses <code>bothE</code> and, later, <code>otherV</code>. </li> <li> In continually traversing over both incoming and outgoing edges, this path is only worth continuing if the edges traversed thus far are only traversed once. That set of edges is maintained in "e". </li> <li> The traversal should repeat until the number of edges traversed in "e" is equal to the total number gathered in the first step above, which would mean that the complete circuit has been made. </li> </ol> </div> <div class="paragraph"> Unlike Königsberg, with just seven bridges, a Eulerian circuit exists in the case with an eighth bridge. The first detected circuit can be displayed with: </div> <section class="tabs tabs-2"> <input id="tab-1729796752-9" type="radio" name="radio-set-1729796752-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796752-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796752-10" type="radio" name="radio-set-1729796752-9" class="tab-selector-2" /> <label for="tab-1729796752-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().sideEffect(outE("bridge").aggregate("bridges")).barrier(). repeat(bothE().or(__.not(select('e')), __.not(filter(__.as('x').select(all, 'e').unfold(). where(eq('x'))))).as('e').otherV()). until(select(all, 'e').count(local).as("c"). select("bridges").count(local).where(eq("c"))).limit(1). path().by(id).by(constant(" -> ")). map {String.join("", it.get().objects())} ==>orange -> blue -> green -> orange -> red -> green -> red -> orange -> blue</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().sideEffect(outE("bridge").aggregate("bridges")).barrier(). repeat(bothE().or(__.not(select('e')), __.not(filter(__.as('x').select(all, 'e').unfold(). where(eq('x'))))).as('e').otherV()). until(select(all, 'e').count(local).as("c"). select("bridges").count(local).where(eq("c"))).limit(1). path().by(id).by(constant(" -> ")). map {String.join("", it.get().objects())}</code></pre> </div> </div> </div> </div> </section> </div> </div> <div class="sect1"> <h2 id="duplicate-edge">Duplicate Edge Detection</h2> <div class="sectionbody"> <div class="paragraph"> Whether part of a graph maintenance process or for some other analysis need, it is sometimes necessary to detect if there is more than one edge between two vertices. The following examples will assume that an edge with the same label and direction will be considered "duplicate". </div> <div class="paragraph"> The "modern" graph does not have any duplicate edges that fit that definition, so the following example adds one that is duplicative of the "created" edge between vertex "1" and "3". </div> <section class="tabs tabs-2"> <input id="tab-1729796763-1" type="radio" name="radio-set-1729796763-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796763-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796763-2" type="radio" name="radio-set-1729796763-1" class="tab-selector-2" /> <label for="tab-1729796763-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(1).as("a").V(3).addE("created").from("a").iterate() gremlin> g.V(1).outE("created") ==>e[0][1-created->3] ==>e[9][1-created->3]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(1).as("a").V(3).addE("created").from("a").iterate() g.V(1).outE("created")</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> One way to find the duplicate edges would be to do something like this: </div> <section class="tabs tabs-2"> <input id="tab-1729796763-3" type="radio" name="radio-set-1729796763-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796763-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796763-4" type="radio" name="radio-set-1729796763-3" class="tab-selector-2" /> <label for="tab-1729796763-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().outE(). project("a","b"). //// (1) by().by(inV().path().by().by(label)). group(). //// (2) by("b"). by(select("a").fold()). unfold(). //// (3) select(values). //// (4) where(count(local).is(gt(1))) ==>[e[0][1-created->3],e[9][1-created->3]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().outE(). project("a","b"). //// (1) by().by(inV().path().by().by(label)). group(). //// (2) by("b"). by(select("a").fold()). unfold(). //// (3) select(values). //// (4) where(count(local).is(gt(1)))</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The "a" and "b" from the <code>project</code> contain the edge and the path respectively. The path consists of a the outgoing vertex, an edge, and the incoming vertex. The use of <code>by().by(label))</code> converts the edge to its label (recall that <code>by</code> are applied in round-robin fashion), so the path will look something like: <code>[v[1],created,v[3]]</code>. </li> <li> Group by the path from "b" and construct a list of edges from "a". Any value in this <code>Map</code> that has a list of edges greater than one means that there is more than one edge for that edge label between those two vertices (i.e. the <code>Map</code> key). </li> <li> Unroll the key-value pairs in the <code>Map</code> of paths-edges. </li> <li> Only the values from the <code>Map</code> are needed and as mentioned earlier, those lists with more than one edge would contain duplicate. </li> </ol> </div> <div class="paragraph"> This method find the duplicates, but does require more memory than other approaches. A slightly more complex approach that uses less memory might look like this: </div> <section class="tabs tabs-2"> <input id="tab-1729796763-5" type="radio" name="radio-set-1729796763-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796763-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796763-6" type="radio" name="radio-set-1729796763-5" class="tab-selector-2" /> <label for="tab-1729796763-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().as("ov"). outE().as("e"). inV().as("iv"). inE(). //// (1) where(neq("e")). //// (2) where(eq("e")).by(label). where(outV().as("ov")). group(). by(select("ov","e","iv").by().by(label)). //// (3) unfold(). //// (4) select(values). where(count(local).is(gt(1))) ==>[e[9][1-created->3],e[0][1-created->3]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().as("ov"). outE().as("e"). inV().as("iv"). inE(). //// (1) where(neq("e")). //// (2) where(eq("e")).by(label). where(outV().as("ov")). group(). by(select("ov","e","iv").by().by(label)). //// (3) unfold(). //// (4) select(values). where(count(local).is(gt(1)))</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> To this point in the traversal, the outgoing edges of a vertex are being iterated with the current edge labeled as "e". For "e", Gremlin traverses to the incoming vertex and back on in edges of that vertex. </li> <li> Those incoming edges are filtered with the following <code>where</code> steps. The first ensures that it does not traverse back over "e" (i.e. the current edge). The second determines if the edge label is equivalent (i.e. the test for the working definition of "duplicate"). The third determines if the outgoing vertex matches the one that started the path labeled as "ov". </li> <li> This line is quite similar to the output achieved in the previous example at step 2. A <code>Map</code> is produced that uses the outgoing vertex, the edge label, and the incoming vertex as the key, with the list of edges for that path as the value. </li> <li> The rest of the traversal is the same as the previous one. </li> </ol> </div> <div class="paragraph"> Note that the above traversal could also be written using <code>match</code> step: </div> <section class="tabs tabs-2"> <input id="tab-1729796763-7" type="radio" name="radio-set-1729796763-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796763-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796763-8" type="radio" name="radio-set-1729796763-7" class="tab-selector-2" /> <label for="tab-1729796763-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().match( __.as("ov").outE().as("e"), __.as("e").inV().as("iv"), __.as("iv").inE().as("ie"), __.as("ie").outV().as("ov")). where("ie",neq("e")). where("ie",eq("e")).by(label). select("ie"). group(). by(select("ov","e","iv").by().by(label)). unfold().select(values). where(count(local).is(gt(1))) ==>[e[9][1-created->3],e[0][1-created->3]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().match( __.as("ov").outE().as("e"), __.as("e").inV().as("iv"), __.as("iv").inE().as("ie"), __.as("ie").outV().as("ov")). where("ie",neq("e")). where("ie",eq("e")).by(label). select("ie"). group(). by(select("ov","e","iv").by().by(label)). unfold().select(values). where(count(local).is(gt(1)))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> A third way to approach this problem would be to force a <a href="https://en.wikipedia.org/wiki/Depth-first_search">depth-first search</a>. The previous examples invoke traversal strategies that force a <a href="https://en.wikipedia.org/wiki/Breadth-first_search">breadth first search</a> as a performance optimization. </div> <section class="tabs tabs-2"> <input id="tab-1729796763-9" type="radio" name="radio-set-1729796763-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796763-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796763-10" type="radio" name="radio-set-1729796763-9" class="tab-selector-2" /> <label for="tab-1729796763-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withoutStrategies(LazyBarrierStrategy, PathRetractionStrategy).V().as("ov"). //// (1) outE().as("e1"). inV().as("iv"). inE(). where(neq("e1")). where(outV().as("ov")).as("e2"). //// (2) where("e1", eq("e2")).by(label) //// (3) ==>e[9][1-created->3] ==>e[0][1-created->3]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withoutStrategies(LazyBarrierStrategy, PathRetractionStrategy).V().as("ov"). //// (1) outE().as("e1"). inV().as("iv"). inE(). where(neq("e1")). where(outV().as("ov")).as("e2"). //// (2) where("e1", eq("e2")).by(label) //3</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Remove strategies that will optimize for breadth first searches and thus allow Gremlin to go depth first. </li> <li> To this point, the traversal is very much like the previous one. Review step 2 in the previous example to see the parallels here. </li> <li> The final <code>where</code> simply looks for edges that match on label, which would then meet the working definition of "duplicate". </li> </ol> </div> <div class="paragraph"> The basic pattern at play here is to compare the path of the outgoing vertex, its outgoing edge label and the incoming vertex. This model can obviously be contracted or expanded as needed to fit different definitions of "duplicate". For example, a "duplicate" definition could extended to the label and properties of the edge. For purposes of demonstration, an additional edge is added to the "modern" graph: </div> <section class="tabs tabs-2"> <input id="tab-1729796763-11" type="radio" name="radio-set-1729796763-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796763-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796763-12" type="radio" name="radio-set-1729796763-11" class="tab-selector-2" /> <label for="tab-1729796763-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(1).as("a").V(3).addE("created").property("weight",0.4d).from("a").iterate() gremlin> g.V(1).as("a").V(3).addE("created").property("weight",0.5d).from("a").iterate() gremlin> g.V(1).outE("created").elementMap() ==>[id:0,label:created,IN:[id:3,label:software],OUT:[id:1,label:person],weight:0.4] ==>[id:9,label:created,IN:[id:3,label:software],OUT:[id:1,label:person],weight:0.4] ==>[id:13,label:created,IN:[id:3,label:software],OUT:[id:1,label:person],weight:0.5]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(1).as("a").V(3).addE("created").property("weight",0.4d).from("a").iterate() g.V(1).as("a").V(3).addE("created").property("weight",0.5d).from("a").iterate() g.V(1).outE("created").elementMap()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> To identify the duplicate with this revised definition, the previous traversal can be modified to: </div> <section class="tabs tabs-2"> <input id="tab-1729796763-13" type="radio" name="radio-set-1729796763-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796763-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796763-14" type="radio" name="radio-set-1729796763-13" class="tab-selector-2" /> <label for="tab-1729796763-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withoutStrategies(LazyBarrierStrategy, PathRetractionStrategy).V().as("ov"). outE().as("e1"). inV().as("iv"). inE(). where(neq("e1")). where(outV().as("ov")).as("e2"). where("e1", eq("e2")).by(label). where("e1", eq("e2")).by("weight").elementMap() ==>[id:9,label:created,IN:[id:3,label:software],OUT:[id:1,label:person],weight:0.4] ==>[id:0,label:created,IN:[id:3,label:software],OUT:[id:1,label:person],weight:0.4]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withoutStrategies(LazyBarrierStrategy, PathRetractionStrategy).V().as("ov"). outE().as("e1"). inV().as("iv"). inE(). where(neq("e1")). where(outV().as("ov")).as("e2"). where("e1", eq("e2")).by(label). where("e1", eq("e2")).by("weight").elementMap()</code></pre> </div> </div> </div> </div> </section> </div> </div> <div class="sect1"> <h2 id="duplicate-vertex">Duplicate Vertex Detection</h2> <div class="sectionbody"> <div class="paragraph"> The pattern for finding duplicate vertices is quite similar to the pattern defined in the <a href="#duplicate-edge">Duplicate Edge</a> section. The idea is to extract the relevant features of the vertex into a comparable list that can then be used to group for duplicates. </div> <div class="paragraph"> Consider the following example with some duplicate vertices added to the "modern" graph: </div> <section class="tabs tabs-2"> <input id="tab-1729796775-1" type="radio" name="radio-set-1729796775-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796775-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796775-2" type="radio" name="radio-set-1729796775-1" class="tab-selector-2" /> <label for="tab-1729796775-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV('person').property('name', 'vadas').property('age', 27) ==>v[0] gremlin> g.addV('person').property('name', 'vadas').property('age', 22) // not a duplicate because "age" value ==>v[13] gremlin> g.addV('person').property('name', 'marko').property('age', 29) ==>v[16] gremlin> g.V().hasLabel("person"). group(). by(values("name", "age").fold()). unfold() ==>[vadas, 27]=[v[0], v[2]] ==>[marko, 29]=[v[16], v[1]] ==>[peter, 35]=[v[6]] ==>[vadas, 22]=[v[13]] ==>[josh, 32]=[v[4]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV('person').property('name', 'vadas').property('age', 27) g.addV('person').property('name', 'vadas').property('age', 22) // not a duplicate because "age" value g.addV('person').property('name', 'marko').property('age', 29) g.V().hasLabel("person"). group(). by(values("name", "age").fold()). unfold()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> In the above case, the "name" and "age" properties are the relevant features for identifying duplication. The key in the <code>Map</code> provided by the <code>group</code> is the list of features for comparison and the value is the list of vertices that match the feature. To extract just those vertices that contain duplicates an additional filter can be added: </div> <section class="tabs tabs-2"> <input id="tab-1729796775-3" type="radio" name="radio-set-1729796775-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796775-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796775-4" type="radio" name="radio-set-1729796775-3" class="tab-selector-2" /> <label for="tab-1729796775-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel("person"). group(). by(values("name", "age").fold()). unfold(). filter(select(values).count(local).is(gt(1))) ==>[vadas, 27]=[v[0], v[2]] ==>[marko, 29]=[v[16], v[1]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel("person"). group(). by(values("name", "age").fold()). unfold(). filter(select(values).count(local).is(gt(1)))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> That filter, extracts the values of the <code>Map</code> and counts the vertices within each list. If that list contains more than one vertex then it is a duplicate. </div> </div> </div> <div class="sect1"> <h2 id="edge-move">Moving an Edge</h2> <div class="sectionbody"> <div class="paragraph"> <img src="../images/gremlin-edge.png" alt="gremlin edge" width="145"> </div> <div class="paragraph"> Aside from their properties, edges are immutable structures where the label and the related in and out vertices cannot be modified. To "move" an edge from one vertex to another, it requires that the edge be dropped and a new edge be created with the same properties and label. It is possible to simulate this "move" in a single traversal as follows: </div> <section class="tabs tabs-2"> <input id="tab-1729796784-1" type="radio" name="radio-set-1729796784-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796784-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796784-2" type="radio" name="radio-set-1729796784-1" class="tab-selector-2" /> <label for="tab-1729796784-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko'). outE().inV(). path().by('name').by(elementMap()) ==>[marko,[id:9,label:created,IN:[id:3,label:software],OUT:[id:1,label:person],weight:0.4],lop] ==>[marko,[id:7,label:knows,IN:[id:2,label:person],OUT:[id:1,label:person],weight:0.5],vadas] ==>[marko,[id:8,label:knows,IN:[id:4,label:person],OUT:[id:1,label:person],weight:1.0],josh]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko'). outE().inV(). path().by('name').by(elementMap())</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The "marko" vertex contains a "knows" edge to the "vadas" vertex. The following code shows how to "move" that edge to the "peter" vertex in a single traversal: </div> <section class="tabs tabs-2"> <input id="tab-1729796784-3" type="radio" name="radio-set-1729796784-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796784-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796784-4" type="radio" name="radio-set-1729796784-3" class="tab-selector-2" /> <label for="tab-1729796784-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko').as('a'). outE('knows').as('e1').filter(inV().has('name','vadas')). //// (1) V().has('name','peter'). addE('knows').from('a').as('e2'). //// (2) sideEffect(select('e1').properties(). unfold().as('p'). select('e2'). property(select('p').key(), select('p').value())). //// (3) select('e1').drop() //// (4) gremlin> g.V().has('name','marko'). outE().inV(). path().by('name').by(elementMap()) ==>[marko,[id:9,label:created,IN:[id:3,label:software],OUT:[id:1,label:person],weight:0.4],lop] ==>[marko,[id:0,label:knows,IN:[id:6,label:person],OUT:[id:1,label:person],weight:0.5],peter] ==>[marko,[id:8,label:knows,IN:[id:4,label:person],OUT:[id:1,label:person],weight:1.0],josh]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko').as('a'). outE('knows').as('e1').filter(inV().has('name','vadas')). //// (1) V().has('name','peter'). addE('knows').from('a').as('e2'). //// (2) sideEffect(select('e1').properties(). unfold().as('p'). select('e2'). property(select('p').key(), select('p').value())). //// (3) select('e1').drop() //// (4) g.V().has('name','marko'). outE().inV(). path().by('name').by(elementMap())</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Find the edge to "move" and label that as "e1". It will be necessary to reference this later to get the edge properties to transfer to the new "moved" edge. </li> <li> Add the "moved" edge and label it as "e2". </li> <li> Use a <code>sideEffect()</code> to transfer the properties from "e1" to "e2". </li> <li> Use <code>drop()</code> to get rid of the old edge at "e1" now that the new "e2" edge is in place. </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="element-existence">Element Existence</h2> <div class="sectionbody"> <div class="paragraph"> Checking for whether or not a graph element is present in the graph is simple: </div> <section class="tabs tabs-2"> <input id="tab-1729796794-1" type="radio" name="radio-set-1729796794-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796794-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796794-2" type="radio" name="radio-set-1729796794-1" class="tab-selector-2" /> <label for="tab-1729796794-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('person','name','marko').hasNext() ==>true gremlin> g.V().has('person','name','stephen').hasNext() ==>false</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('person','name','marko').hasNext() g.V().has('person','name','stephen').hasNext()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Knowing that an element exists or not is usually a common point of decision in determining the appropriate path of code to take. In the example above, the check is for vertex existence and a typical reason to check for existence is to determine whether or not to add a new vertex or to return the one that exists (i.e. "get or create" pattern). This entire operation can occur in a single traversal. </div> <section class="tabs tabs-2"> <input id="tab-1729796794-3" type="radio" name="radio-set-1729796794-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796794-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796794-4" type="radio" name="radio-set-1729796794-3" class="tab-selector-2" /> <label for="tab-1729796794-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('person','name','marko'). fold(). coalesce(unfold(), addV('person'). property('name','marko'). property('age',29)) ==>v[1] gremlin> g.V().has('person','name','stephen'). fold(). coalesce(unfold(), addV('person'). property('name','stephen'). property('age',34)) ==>v[0]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('person','name','marko'). fold(). coalesce(unfold(), addV('person'). property('name','marko'). property('age',29)) g.V().has('person','name','stephen'). fold(). coalesce(unfold(), addV('person'). property('name','stephen'). property('age',34))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> This use of <code>coalesce()</code> shown above is the basis for this pattern. Note that at the end of <code>has()</code>-step there is either a vertex or not. By using <code>fold()</code>, "existence" or "not existence" is reduced to a <code>List</code> with the vertex or a <code>List</code> with no values. With a <code>List</code> as the traverser flowing into <code>coalesce()</code> the first child traversal to return something will execute. If the <code>List</code> has a vertex then it will <code>unfold()</code> and return the existing one. If it is empty, then the vertex does not exist and it is added and returned. </div> <div class="paragraph"> This "get or create" logic can be expanded to be "upsert" like functionality as follows: </div> <section class="tabs tabs-2"> <input id="tab-1729796794-5" type="radio" name="radio-set-1729796794-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796794-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796794-6" type="radio" name="radio-set-1729796794-5" class="tab-selector-2" /> <label for="tab-1729796794-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('person','name','marko'). fold(). coalesce(unfold(), addV('person').property('name','marko')). property('age',29) ==>v[1] gremlin> g.V().has('person','name','stephen'). fold(). coalesce(unfold(), addV('person').property('name','stephen')). property('age',34) ==>v[13]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('person','name','marko'). fold(). coalesce(unfold(), addV('person').property('name','marko')). property('age',29) g.V().has('person','name','stephen'). fold(). coalesce(unfold(), addV('person').property('name','stephen')). property('age',34)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> By moving the <code>property()</code>-step that set the "age" value outside of <code>coalesce()</code>, the property is then set for both newly created vertices and for existing ones. </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <div class="title">Warning</div> </td> <td class="content"> Always consider the specific nature of the graph implementation in use when considering these patterns. Some graph databases may not treat these traversals as true "upsert" operations and may do a "read before write" in their execution. </td> </tr> </table> </div> <div class="paragraph"> It is possible to do similar sorts of operations with edges using the same pattern: </div> <section class="tabs tabs-2"> <input id="tab-1729796794-7" type="radio" name="radio-set-1729796794-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796794-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796794-8" type="radio" name="radio-set-1729796794-7" class="tab-selector-2" /> <label for="tab-1729796794-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('person','name','vadas').as('v'). V().has('software','name','ripple'). coalesce(__.inE('created').where(outV().as('v')), addE('created').from('v').property('weight',0.5)) ==>e[0][2-created->5]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('person','name','vadas').as('v'). V().has('software','name','ripple'). coalesce(__.inE('created').where(outV().as('v')), addE('created').from('v').property('weight',0.5))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> In this case, the adjacent vertices of the edge are retrieved first and within the <code>coalesce()</code>, the existence of the edge is checked with <code>where()</code> using a matching pattern on the "v" label and returned if found. If the edge is not found between these two vertices, then it is created as part of the second traversal given to <code>coalesce()</code>. </div> </div> </div> <div class="sect1"> <h2 id="if-then-based-grouping">If-Then Based Grouping</h2> <div class="sectionbody"> <div class="paragraph"> Consider the following traversal over the "modern" toy graph: </div> <section class="tabs tabs-2"> <input id="tab-1729796804-1" type="radio" name="radio-set-1729796804-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796804-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796804-2" type="radio" name="radio-set-1729796804-1" class="tab-selector-2" /> <label for="tab-1729796804-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel('person').groupCount().by('age') ==>[32:1,35:1,27:1,29:1]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel('person').groupCount().by('age')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The result is an age distribution that simply shows that every "person" in the graph is of a different age. In some cases, this result is exactly what is needed, but sometimes a grouping may need to be transformed to provide a different picture of the result. For example, perhaps a grouping on the value "age" would be better represented by a domain concept such as "young", "old" and "very old". </div> <section class="tabs tabs-2"> <input id="tab-1729796804-3" type="radio" name="radio-set-1729796804-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796804-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796804-4" type="radio" name="radio-set-1729796804-3" class="tab-selector-2" /> <label for="tab-1729796804-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel("person").groupCount().by(values("age").choose( is(lt(28)),constant("young"), choose(is(lt(30)), constant("old"), constant("very old")))) ==>[young:1,old:1,very old:2]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel("person").groupCount().by(values("age").choose( is(lt(28)),constant("young"), choose(is(lt(30)), constant("old"), constant("very old"))))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Note that the <code>by</code> modulator has been altered from simply taking a string key of "age" to take a <code>Traversal</code>. That inner <code>Traversal</code> utilizes <code>choose</code> which is like an <code>if-then-else</code> clause. The <code>choose</code> is nested and would look like the following in Java: </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java">if (age < 28) { return "young"; } else { if (age < 30) { return "old"; } else { return "very old"; } }</code></pre> </div> </div> <div class="paragraph"> The use of <code>choose</code> is a good intuitive choice for this <code>Traversal</code> as it is a natural mapping to <code>if-then-else</code>, but there is another option to consider with <code>coalesce</code>: </div> <section class="tabs tabs-2"> <input id="tab-1729796804-5" type="radio" name="radio-set-1729796804-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796804-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796804-6" type="radio" name="radio-set-1729796804-5" class="tab-selector-2" /> <label for="tab-1729796804-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel("person"). groupCount().by(values("age"). coalesce(is(lt(28)).constant("young"), is(lt(30)).constant("old"), constant("very old"))) ==>[young:1,old:1,very old:2]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel("person"). groupCount().by(values("age"). coalesce(is(lt(28)).constant("young"), is(lt(30)).constant("old"), constant("very old")))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The answer is the same, but this traversal removes the nested <code>choose</code>, which makes it easier to read. </div> </div> </div> <div class="sect1"> <h2 id="looping">Looping</h2> <div class="sectionbody"> <div class="paragraph"> One common use case when working with Gremlin is to perform complex looping statements using the <code>repeat()</code> step. While many of the common patterns for looping within traversals are discussed in the documentation there are several more complex patterns that include additional steps which are also commonly used. This section attempts to demonstrate how to use some of these more complex measurements. </div> <div class="paragraph"> <img src="../images/tree-lca.png" alt="tree lca" width="230"> The following examples will use this graph depicted here: </div> <section class="tabs tabs-2"> <input id="tab-1729796814-1" type="radio" name="radio-set-1729796814-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796814-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796814-2" type="radio" name="radio-set-1729796814-1" class="tab-selector-2" /> <label for="tab-1729796814-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id, 'A').as('a'). addV().property(id, 'B').as('b'). addV().property(id, 'C').as('c'). addV().property(id, 'D').as('d'). addV().property(id, 'E').as('e'). addV().property(id, 'F').as('f'). addV().property(id, 'G').as('g'). addE('hasParent').from('a').to('b'). addE('hasParent').from('b').to('c'). addE('hasParent').from('d').to('c'). addE('hasParent').from('c').to('e'). addE('hasParent').from('e').to('f'). addE('hasParent').from('g').to('f').iterate()</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id, 'A').as('a'). addV().property(id, 'B').as('b'). addV().property(id, 'C').as('c'). addV().property(id, 'D').as('d'). addV().property(id, 'E').as('e'). addV().property(id, 'F').as('f'). addV().property(id, 'G').as('g'). addE('hasParent').from('a').to('b'). addE('hasParent').from('b').to('c'). addE('hasParent').from('d').to('c'). addE('hasParent').from('c').to('e'). addE('hasParent').from('e').to('f'). addE('hasParent').from('g').to('f').iterate()</code></pre> </div> </div> </div> </div> </section> <div class="sect2"> <h3 id="_conditional_looping_with_max_depth">Conditional Looping with Max Depth</h3> <div class="paragraph"> One common situation encountered when writing <code>repeat()</code> loop is the need to exit the loop when either a specific condition is met or a maximum depth is reached. Given that graph above the following traversal demonstrates how to accomplish this type of complex exit condition. In this example the traversal will start at vertex A and loop through all outgoing edges until it reaches vertex C or until it has completed 3 loops. </div> <section class="tabs tabs-2"> <input id="tab-1729796814-3" type="radio" name="radio-set-1729796814-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796814-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796814-4" type="radio" name="radio-set-1729796814-3" class="tab-selector-2" /> <label for="tab-1729796814-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V('A'). repeat(out().simplePath()). until(hasId('C').or().loops().is(3)) ==>v[C]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V('A'). repeat(out().simplePath()). until(hasId('C').or().loops().is(3))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> In the above case the traversal processes the <code>out().simplePath()</code> step once to move from vertex A to vertex B, a second time to move from vertex B to vertex C, and then exits the traversal because it satisfies the <code>hasId('C')</code> condition since it’s reached vertex C. If we however change that exit condition to be vertex G, we will see that this traversal now will continue to process thorough vertex X and will exit based on reaching the maximum number of loops (3). </div> <section class="tabs tabs-2"> <input id="tab-1729796814-5" type="radio" name="radio-set-1729796814-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796814-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796814-6" type="radio" name="radio-set-1729796814-5" class="tab-selector-2" /> <label for="tab-1729796814-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V('A'). repeat(out().simplePath()). until(hasId('G').or().loops().is(3)) ==>v[E]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V('A'). repeat(out().simplePath()). until(hasId('G').or().loops().is(3))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The key portion of the above traversal is the <code>until()</code> step. This step is capable of accepting a <code>Traversal</code> object which continues the <code>repeat()</code> loop traversing until the evaluated output of the traversal is true, when the traverser exits the <code>repeat()</code> loop. This methodology allows complex logical conditions to be used as the exit criteria. </div> </div> <div class="sect2"> <h3 id="_emitting_loop_depth">Emitting Loop Depth</h3> <div class="paragraph"> Another common situation encountered when using <code>repeat()</code> loops is the desire to emit not only the value of the traverser at each step, but also to emit the depth of that element in the repeat loop. Below are several different recipes for accomplishing this task based on what the desired output: </div> <div class="paragraph"> If the desired output is to get each vertex and its associated depth this can be accomplished using this traversal. </div> <section class="tabs tabs-2"> <input id="tab-1729796814-7" type="radio" name="radio-set-1729796814-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796814-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796814-8" type="radio" name="radio-set-1729796814-7" class="tab-selector-2" /> <label for="tab-1729796814-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSack(1).V('A'). repeat(both().simplePath(). sack(assign).by(loops())). emit(). project('vertex', 'depth'). by(). by(sack()) ==>[vertex:v[B],depth:0] ==>[vertex:v[C],depth:1] ==>[vertex:v[E],depth:2] ==>[vertex:v[D],depth:2] ==>[vertex:v[F],depth:3] ==>[vertex:v[G],depth:4]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSack(1).V('A'). repeat(both().simplePath(). sack(assign).by(loops())). emit(). project('vertex', 'depth'). by(). by(sack())</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> However, if the desired output is to get a single result per level containing all the vertices at that level this can be accomplished with this traversal. </div> <section class="tabs tabs-2"> <input id="tab-1729796814-9" type="radio" name="radio-set-1729796814-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796814-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796814-10" type="radio" name="radio-set-1729796814-9" class="tab-selector-2" /> <label for="tab-1729796814-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V('A'). repeat(both().simplePath(). group('x'). by(loops())). emit(). times(3). cap('x') ==>[0:[v[B]],1:[v[C]],2:[v[E],v[D]]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V('A'). repeat(both().simplePath(). group('x'). by(loops())). emit(). times(3). cap('x')</code></pre> </div> </div> </div> </div> </section> </div> <div class="sect2"> <h3 id="_optional_loop_depth">Optional Loop Depth</h3> <div class="paragraph"> A third common use of <code>repeat()</code> loops is to loop through a series of steps a certain number of times or until there are no additional edges to traverse. The examples below demonstrate how this loop termination can be accomplished. </div> <div class="paragraph"> The first method, is an extension of our "Conditional Looping with Max Depth" pattern above where the condition in the <code>until()</code> checking for a vertex with a degree of zero. </div> <section class="tabs tabs-2"> <input id="tab-1729796814-11" type="radio" name="radio-set-1729796814-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796814-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796814-12" type="radio" name="radio-set-1729796814-11" class="tab-selector-2" /> <label for="tab-1729796814-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V('A'). repeat(out().simplePath()). until(outE().count().is(0).or().loops().is(5)) ==>v[F]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V('A'). repeat(out().simplePath()). until(outE().count().is(0).or().loops().is(5))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Another way to accomplish this requirement is to use the <code>optional()</code> step. Here use the <code>optional()</code> step within a <code>repeat().times()</code> loop. In the example below we start at vertex A and traverse all <code>out()</code> edges up to a maximum of 5 times. </div> <section class="tabs tabs-2"> <input id="tab-1729796814-13" type="radio" name="radio-set-1729796814-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796814-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796814-14" type="radio" name="radio-set-1729796814-13" class="tab-selector-2" /> <label for="tab-1729796814-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V('A').repeat(optional(out())).times(5) ==>v[F]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V('A').repeat(optional(out())).times(5)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Each of these patterns can be combined with any variety of other steps to satisfy more complex traversal requirements. For example, we can first use a more traditional <code>repeat()</code> loop to start at vertex A, traverse all <code>both()</code> edges two times, and then traverse <code>out()</code> edges up to five times. </div> <section class="tabs tabs-2"> <input id="tab-1729796814-15" type="radio" name="radio-set-1729796814-15" class="tab-selector-1" checked="checked" /> <label for="tab-1729796814-15" class="tab-label-1">console (groovy)</label> <input id="tab-1729796814-16" type="radio" name="radio-set-1729796814-15" class="tab-selector-2" /> <label for="tab-1729796814-16" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V('A').repeat(both()).times(2).repeat(optional(out())).times(5) ==>v[F] ==>v[F]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V('A').repeat(both()).times(2).repeat(optional(out())).times(5)</code></pre> </div> </div> </div> </div> </section> </div> </div> </div> <div class="sect1"> <h2 id="operating-on-dropped-elements">Operating on Dropped Elements</h2> <div class="sectionbody"> <div class="paragraph"> One common scenario that happens when dropping elements using a traversal is the desire to perform some sort of operation on the elements being removed. This simplest is returning the number of elements being dropped from the traversal, which is shown in the example below from the "modern" graph. </div> <section class="tabs tabs-2"> <input id="tab-1729796825-1" type="radio" name="radio-set-1729796825-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796825-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796825-2" type="radio" name="radio-set-1729796825-1" class="tab-selector-2" /> <label for="tab-1729796825-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('lang', 'java').sideEffect(drop()).count() ==>2</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('lang', 'java').sideEffect(drop()).count()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> While this may seem a bit counterintuitive, what is occurring in this recipe is that the <code>sideEffect()</code> step is performing the <code>drop()</code> while each of the input traverser is still passed along to the remainder of the traversal, which in this case is a <code>count()</code> operation. This pattern can be extended beyond a simple count to perform a variety of more complex traversals based on the dropped traversal such as removing child nodes in the case of a tree or setting properties on adjacent vertices. </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <div class="title">Warning</div> </td> <td class="content"> Some graph implementations may not behave in the same manner as TinkerGraph when using side effects, such as the <code>sideEffect(drop())</code>. While the specified pattern works for TinkerGraph, we recommend that this pattern be tested on your chosen implementation to ensure that it functions in the same manner. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="pagination">Pagination</h2> <div class="sectionbody"> <div class="paragraph"> <img src="../images/gremlin-paging.png" alt="gremlin paging" width="330">In most database applications, it is oftentimes desirable to return discrete blocks of data for a query rather than all of the data that the total results would contain. This approach to returning data is referred to as "pagination" and typically involves a situation where the client executing the query can specify the start position and end position (or the amount of data to return in lieu of the end position) representing the block of data to return. In this way, one could return the first ten records of one hundred, then the second ten records and so on, until potentially all one hundred were returned. </div> <div class="paragraph"> In Gremlin, a basic approach to paging would look something like the following: </div> <section class="tabs tabs-2"> <input id="tab-1729796834-1" type="radio" name="radio-set-1729796834-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796834-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796834-2" type="radio" name="radio-set-1729796834-1" class="tab-selector-2" /> <label for="tab-1729796834-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel('person').fold() //// (1) ==>[v[1],v[2],v[4],v[6]] gremlin> g.V().hasLabel('person'). fold().as('persons','count'). select('persons','count'). by(range(local, 0, 2)). by(count(local)) //// (2) ==>[persons:[v[1],v[2]],count:4] gremlin> g.V().hasLabel('person'). fold().as('persons','count'). select('persons','count'). by(range(local, 2, 4)). by(count(local)) //// (3) ==>[persons:[v[4],v[6]],count:4]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel('person').fold() //// (1) g.V().hasLabel('person'). fold().as('persons','count'). select('persons','count'). by(range(local, 0, 2)). by(count(local)) //// (2) g.V().hasLabel('person'). fold().as('persons','count'). select('persons','count'). by(range(local, 2, 4)). by(count(local)) //3</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Gets all the "person" vertices. </li> <li> Gets the first two "person" vertices and includes the total number of vertices so that the client knows how many it has to page through. </li> <li> Gets the final two "person" vertices. </li> </ol> </div> <div class="paragraph"> From a functional perspective, the above example shows a fairly standard paging model. Unfortunately, there is a problem. To get the total number of vertices, the traversal must first <code>fold()</code> them, which iterates out the traversal bringing them all into memory. If the number of "person" vertices is large, that step could lead to a long running traversal and perhaps one that would simply run out of memory prior to completion. There is no shortcut to getting a total count without doing a full iteration of the traversal. If the requirement for a total count is removed then the traversals become more simple: </div> <section class="tabs tabs-2"> <input id="tab-1729796834-3" type="radio" name="radio-set-1729796834-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796834-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796834-4" type="radio" name="radio-set-1729796834-3" class="tab-selector-2" /> <label for="tab-1729796834-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel('person').range(0,2) ==>v[1] ==>v[2] gremlin> g.V().hasLabel('person').range(2,4) ==>v[4] ==>v[6]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel('person').range(0,2) g.V().hasLabel('person').range(2,4)</code></pre> </div> </div> </div> </div> </section> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> The first traversal above could also be written as <code>g.V().hasLabel('person').limit(2)</code>. </td> </tr> </table> </div> <div class="paragraph"> In this case, there is no way to know the total count so the only way to know if the end of the results have been reached is to count the results from each paged result to see if there’s less than the number expected or simply zero results. In that case, further requests for additional pages would be unnecessary. Of course, this approach is not free of problems either. Most graph databases will not optimize the <code>range()</code>-step, meaning that the second traversal will repeat the iteration of the first two vertices to get to the second set of two vertices. In other words, for the second traversal, the graph will still read four vertices even though there was only a request for two. </div> <div class="paragraph"> The only way to completely avoid that problem is to re-use the same traversal instance: </div> <section class="tabs tabs-2"> <input id="tab-1729796834-5" type="radio" name="radio-set-1729796834-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796834-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796834-6" type="radio" name="radio-set-1729796834-5" class="tab-selector-2" /> <label for="tab-1729796834-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> t = g.V().hasLabel('person');[] gremlin> t.next(2) ==>v[1] ==>v[2] gremlin> t.next(2) ==>v[4] ==>v[6]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">t = g.V().hasLabel('person');[] t.next(2) t.next(2)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> A further consideration relates to the order in which results are returned. TinkerPop does not guarantee that the order of the items returned on the same traversal will be the same order each time the traversal is iterated. TinkerPop only guarantees that it does not re-shuffle the order provided by the underlying graph database. This guarantee has two implications: </div> <div class="olist arabic"> <ol class="arabic"> <li> Iteration order is dependent on the underlying graph database. Some graphs may guarantee ordering and some may not and still some others may guarantee ordering but only under certain conditions. Consult the documentation of the graph database for more information on this. </li> <li> Use <code>order()</code>-step to make iteration order explicit if guarantees are required. </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="recommendation">Recommendation</h2> <div class="sectionbody"> <div class="paragraph"> <img src="../images/gremlin-recommendation.png" alt="gremlin recommendation" width="180">One of the more common use cases for a graph database is the development of <a href="https://en.wikipedia.org/wiki/Recommender_system">recommendation systems</a> and a simple approach to doing that is through <a href="https://en.wikipedia.org/wiki/Collaborative_filtering">collaborative filtering</a>. Collaborative filtering assumes that if a person shares one set of opinions with a different person, they are likely to have similar taste with respect to other issues. With that basis in mind, it is then possible to make predictions for a specific person as to what their opinions might be. </div> <div class="paragraph"> As a simple example, consider a graph that contains "person" and "product" vertices connected by "bought" edges. The following script generates some data for the graph using that basic schema: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-1" type="radio" name="radio-set-1729796844-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-2" type="radio" name="radio-set-1729796844-1" class="tab-selector-2" /> <label for="tab-1729796844-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV("person").property("name","alice"). addV("person").property("name","bob"). addV("person").property("name","jon"). addV("person").property("name","jack"). addV("person").property("name","jill").iterate() gremlin> (1..10).each { g.addV("product").property("name","product #${it}").iterate() }; [] gremlin> (3..7).each { g.V().has("person","name","alice").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; [] gremlin> (1..5).each { g.V().has("person","name","bob").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; [] gremlin> (6..10).each { g.V().has("person","name","jon").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; [] gremlin> 1.step(10, 2) { g.V().has("person","name","jack").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; [] gremlin> 2.step(10, 2) { g.V().has("person","name","jill").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; []</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV("person").property("name","alice"). addV("person").property("name","bob"). addV("person").property("name","jon"). addV("person").property("name","jack"). addV("person").property("name","jill").iterate() (1..10).each { g.addV("product").property("name","product #${it}").iterate() }; [] (3..7).each { g.V().has("person","name","alice").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; [] (1..5).each { g.V().has("person","name","bob").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; [] (6..10).each { g.V().has("person","name","jon").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; [] 1.step(10, 2) { g.V().has("person","name","jack").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; [] 2.step(10, 2) { g.V().has("person","name","jill").as("p"). V().has("product","name","product #${it}").addE("bought").from("p").iterate() }; []</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The first step to making a recommendation to "alice" using collaborative filtering is to understand what she bought: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-3" type="radio" name="radio-set-1729796844-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-4" type="radio" name="radio-set-1729796844-3" class="tab-selector-2" /> <label for="tab-1729796844-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','alice').out('bought').values('name') ==>product #5 ==>product #6 ==>product #7 ==>product #3 ==>product #4</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','alice').out('bought').values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The following diagram depicts one of the edges traversed in the above example between "alice" and "product #5". Obviously, the other products "alice" bought would have similar relations, but this diagram and those to follow will focus on the neighborhood around that product. </div> <div class="paragraph"> <img src="../images/recommendation-alice-1.png" alt="recommendation alice 1" width="500"> </div> <div class="paragraph"> The next step is to determine who else purchased those products: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-5" type="radio" name="radio-set-1729796844-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-6" type="radio" name="radio-set-1729796844-5" class="tab-selector-2" /> <label for="tab-1729796844-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','alice').out('bought').in('bought').dedup().values('name') ==>alice ==>bob ==>jack ==>jill ==>jon</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','alice').out('bought').in('bought').dedup().values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> It is worth noting that "alice" is in the results above. She should really be excluded from the list as the interest is in what individuals other than herself purchased: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-7" type="radio" name="radio-set-1729796844-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-8" type="radio" name="radio-set-1729796844-7" class="tab-selector-2" /> <label for="tab-1729796844-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','alice').as('her'). out('bought'). in('bought').where(neq('her')). dedup().values('name') ==>bob ==>jack ==>jill ==>jon</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','alice').as('her'). out('bought'). in('bought').where(neq('her')). dedup().values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The following diagram shows "alice" and those others who purchased "product #5". </div> <div class="paragraph"> <img src="../images/recommendation-alice-2.png" alt="recommendation alice 2" width="600"> </div> <div class="paragraph"> The knowledge of the people who bought the same things as "alice" can then be used to find the set of products that they bought: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-9" type="radio" name="radio-set-1729796844-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-10" type="radio" name="radio-set-1729796844-9" class="tab-selector-2" /> <label for="tab-1729796844-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','alice').as('her'). out('bought'). in('bought').where(neq('her')). out('bought'). dedup().values('name') ==>product #1 ==>product #2 ==>product #3 ==>product #4 ==>product #5 ==>product #7 ==>product #9 ==>product #6 ==>product #8 ==>product #10</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','alice').as('her'). out('bought'). in('bought').where(neq('her')). out('bought'). dedup().values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> <img src="../images/recommendation-alice-3.png" alt="recommendation alice 3" width="800"> </div> <div class="paragraph"> This set of products could be the basis for recommendation, but it is important to remember that "alice" may have already purchased some of these products and it would be better to not pester her with recommendations for products that she already owns. Those products she already purchased can be excluded as follows: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-11" type="radio" name="radio-set-1729796844-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-12" type="radio" name="radio-set-1729796844-11" class="tab-selector-2" /> <label for="tab-1729796844-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','alice').as('her'). out('bought').aggregate('self'). in('bought').where(neq('her')). out('bought').where(without('self')). dedup().values('name') ==>product #1 ==>product #2 ==>product #9 ==>product #8 ==>product #10</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','alice').as('her'). out('bought').aggregate('self'). in('bought').where(neq('her')). out('bought').where(without('self')). dedup().values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> <img src="../images/recommendation-alice-4.png" alt="recommendation alice 4" width="800"> </div> <div class="paragraph"> The final step would be to group the remaining products (instead of <code>dedup()</code> which was mostly done for demonstration purposes) to form a ranking: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-13" type="radio" name="radio-set-1729796844-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-14" type="radio" name="radio-set-1729796844-13" class="tab-selector-2" /> <label for="tab-1729796844-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('person','name','alice').as('her'). //// (1) out('bought').aggregate('self'). //// (2) in('bought').where(neq('her')). //// (3) out('bought').where(without('self')). //// (4) groupCount(). order(local). by(values, desc) //// (5) ==>[v[10]:6,v[26]:5,v[12]:5,v[24]:4,v[28]:2]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('person','name','alice').as('her'). //// (1) out('bought').aggregate('self'). //// (2) in('bought').where(neq('her')). //// (3) out('bought').where(without('self')). //// (4) groupCount(). order(local). by(values, desc) //5</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Find "alice" who is the person for whom the product recommendation is being made. </li> <li> Traverse to the products that "alice" bought and gather them for later use in the traversal. </li> <li> Traverse to the "person" vertices who bought the products that "alice" bought and exclude "alice" herself from that list. </li> <li> Given those people who bought similar products to "alice", find the products that they bought and exclude those that she already bought. </li> <li> Group the products and count the number of times they were purchased by others to come up with a ranking of products to recommend to "alice". </li> </ol> </div> <div class="paragraph"> The previous example was already described as "basic" and obviously could take into account whatever data is available to further improve the quality of the recommendation (e.g. product ratings, times of purchase, etc.). One option to improve the quality of what is recommended (without expanding the previous dataset) might be to choose the person vertices that make up the recommendation to "alice" who have the largest common set of purchases. </div> <div class="paragraph"> Looking back to the previous code example, consider its more strip down representation that shows those individuals who have at least one product in common: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-15" type="radio" name="radio-set-1729796844-15" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-15" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-16" type="radio" name="radio-set-1729796844-15" class="tab-selector-2" /> <label for="tab-1729796844-16" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup() ==>v[2] ==>v[6] ==>v[8] ==>v[4]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Next, do some grouping to find count how many products they have in common: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-17" type="radio" name="radio-set-1729796844-17" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-17" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-18" type="radio" name="radio-set-1729796844-17" class="tab-selector-2" /> <label for="tab-1729796844-18" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()) ==>[v[2]:3,v[4]:2,v[6]:3,v[8]:2]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count())</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The above output shows that the best that can be expected is three common products. The traversal needs to be aware of that maximum: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-19" type="radio" name="radio-set-1729796844-19" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-19" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-20" type="radio" name="radio-set-1729796844-19" class="tab-selector-2" /> <label for="tab-1729796844-20" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()). select(values). order(local). by(desc).limit(local, 1) ==>3</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()). select(values). order(local). by(desc).limit(local, 1)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> With the maximum value available, it can be used to chose those "person" vertices that have the three products in common: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-21" type="radio" name="radio-set-1729796844-21" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-21" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-22" type="radio" name="radio-set-1729796844-21" class="tab-selector-2" /> <label for="tab-1729796844-22" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()).as("g"). select(values). order(local). by(desc).limit(local, 1).as("m"). select("g").unfold(). where(select(values).as("m")).select(keys) ==>v[2] ==>v[6]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()).as("g"). select(values). order(local). by(desc).limit(local, 1).as("m"). select("g").unfold(). where(select(values).as("m")).select(keys)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Now that there is a list of "person" vertices to base the recommendation on, traverse to the products that they purchased: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-23" type="radio" name="radio-set-1729796844-23" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-23" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-24" type="radio" name="radio-set-1729796844-23" class="tab-selector-2" /> <label for="tab-1729796844-24" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()).as("g"). select(values). order(local). by(desc).limit(local, 1).as("m"). select("g").unfold(). where(select(values).as("m")).select(keys). out("bought").where(without("self")) ==>v[10] ==>v[12] ==>v[26] ==>v[10]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()).as("g"). select(values). order(local). by(desc).limit(local, 1).as("m"). select("g").unfold(). where(select(values).as("m")).select(keys). out("bought").where(without("self"))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The above output shows that one product is held in common making it the top recommendation: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-25" type="radio" name="radio-set-1729796844-25" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-25" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-26" type="radio" name="radio-set-1729796844-25" class="tab-selector-2" /> <label for="tab-1729796844-26" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()).as("g"). select(values). order(local). by(desc).limit(local, 1).as("m"). select("g").unfold(). where(select(values).as("m")).select(keys). out("bought").where(without("self")). groupCount(). order(local). by(values, desc). by(select(keys).values("name")). unfold().select(keys).values("name") ==>product #1 ==>product #2 ==>product #9</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("person","name","alice").as("alice"). out("bought").aggregate("self"). in("bought").where(neq("alice")).dedup(). group(). by().by(out("bought"). where(within("self")).count()).as("g"). select(values). order(local). by(desc).limit(local, 1).as("m"). select("g").unfold(). where(select(values).as("m")).select(keys). out("bought").where(without("self")). groupCount(). order(local). by(values, desc). by(select(keys).values("name")). unfold().select(keys).values("name")</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> In considering the practical applications of this recipe, it is worth revisiting the earlier "basic" version of the recommendation algorithm: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-27" type="radio" name="radio-set-1729796844-27" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-27" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-28" type="radio" name="radio-set-1729796844-27" class="tab-selector-2" /> <label for="tab-1729796844-28" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('person','name','alice').as('her'). out('bought').aggregate('self'). in('bought').where(neq('her')). out('bought').where(without('self')). groupCount(). order(local). by(values, desc) ==>[v[10]:6,v[26]:5,v[12]:5,v[24]:4,v[28]:2]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('person','name','alice').as('her'). out('bought').aggregate('self'). in('bought').where(neq('her')). out('bought').where(without('self')). groupCount(). order(local). by(values, desc)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The above traversal performs a full ranking of items based on all the connected data. That could be a time consuming operation depending on the number of paths being traversed. As it turns out, recommendations don’t need to have perfect knowledge of all data to provide a "pretty good" approximation of a recommendation. It can therefore make sense to place additional limits on the traversal to have it better return more quickly at the expense of examining less data. </div> <div class="paragraph"> Gremlin provides a number of steps that can help with these limits like: <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#coin-step">coin()</a>, <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#sample-step">sample()</a>, and <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#timelimit-step">timeLimit()</a>. For example, to have the traversal sample the data for no longer than one second, the previous "basic" recommendation could be changed to: </div> <section class="tabs tabs-2"> <input id="tab-1729796844-29" type="radio" name="radio-set-1729796844-29" class="tab-selector-1" checked="checked" /> <label for="tab-1729796844-29" class="tab-label-1">console (groovy)</label> <input id="tab-1729796844-30" type="radio" name="radio-set-1729796844-29" class="tab-selector-2" /> <label for="tab-1729796844-30" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('person','name','alice').as('her'). out('bought').aggregate('self'). in('bought').where(neq('her')). out('bought').where(without('self')).timeLimit(1000). groupCount(). order(local). by(values, desc) ==>[v[10]:6,v[26]:5,v[12]:5,v[24]:4,v[28]:2]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('person','name','alice').as('her'). out('bought').aggregate('self'). in('bought').where(neq('her')). out('bought').where(without('self')).timeLimit(1000). groupCount(). order(local). by(values, desc)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> In using sampling methods, it is important to consider that the natural ordering of edges in the graph may not produce an ideal sample for the recommendation. For example, if the edges end up being returned oldest first, then the recommendation will be based on the oldest data, which would not be ideal. As with any traversal, it is important to understand the nature of the graph being traversed and the behavior of the underlying graph database to properly achieve the desired outcome. </div> </div> </div> <div class="sect1"> <h2 id="shortest-path">Shortest Path</h2> <div class="sectionbody"> <div class="paragraph"> <img src="../images/shortest-path.png" alt="shortest path" width="300"> </div> <div class="paragraph"> When working with a graph, it is often necessary to identify the <a href="https://en.wikipedia.org/wiki/Shortest_path_problem">shortest path</a> between two identified vertices. The following is a simple example that identifies the shortest path between vertex "1" and vertex "5" while traversing over out edges: </div> <section class="tabs tabs-2"> <input id="tab-1729796857-1" type="radio" name="radio-set-1729796857-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796857-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796857-2" type="radio" name="radio-set-1729796857-1" class="tab-selector-2" /> <label for="tab-1729796857-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id, 1).as('1'). addV().property(id, 2).as('2'). addV().property(id, 3).as('3'). addV().property(id, 4).as('4'). addV().property(id, 5).as('5'). addE('knows').from('1').to('2'). addE('knows').from('2').to('4'). addE('knows').from('4').to('5'). addE('knows').from('2').to('3'). addE('knows').from('3').to('4').iterate() gremlin> g.V(1).repeat(out().simplePath()).until(hasId(5)).path().limit(1) //// (1) ==>[v[1],v[2],v[4],v[5]] gremlin> g.V(1).repeat(out().simplePath()).until(hasId(5)).path().count(local) //// (2) ==>4 ==>5 gremlin> g.V(1).repeat(out().simplePath()).until(hasId(5)).path(). group().by(count(local)).next() //// (3) ==>4=[path[v[1], v[2], v[4], v[5]]] ==>5=[path[v[1], v[2], v[3], v[4], v[5]]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id, 1).as('1'). addV().property(id, 2).as('2'). addV().property(id, 3).as('3'). addV().property(id, 4).as('4'). addV().property(id, 5).as('5'). addE('knows').from('1').to('2'). addE('knows').from('2').to('4'). addE('knows').from('4').to('5'). addE('knows').from('2').to('3'). addE('knows').from('3').to('4').iterate() g.V(1).repeat(out().simplePath()).until(hasId(5)).path().limit(1) //// (1) g.V(1).repeat(out().simplePath()).until(hasId(5)).path().count(local) //// (2) g.V(1).repeat(out().simplePath()).until(hasId(5)).path(). group().by(count(local)).next() //3</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The traversal starts at vertex with the identifier of "1" and repeatedly traverses on out edges "until" it finds a vertex with an identifier of "5". The inclusion of <code>simplePath</code> within the <code>repeat</code> is present to filter out repeated paths. The traversal terminates with <code>limit</code> in this case as the first path returned will be the shortest one. Of course, it is possible for there to be more than one path in the graph of the same length (i.e. two or more paths of length three), but this example is not considering that. </li> <li> It might be interesting to know the path lengths for all paths between vertex "1" and "5". </li> <li> Alternatively, one might wish to do a path length distribution over all the paths. </li> </ol> </div> <div class="paragraph"> The following code block demonstrates how the shortest path from <code>v[1]</code> to <code>v[5]</code> can be queried in OLAP, using the <code>shortestPath()</code> step. </div> <section class="tabs tabs-2"> <input id="tab-1729796857-3" type="radio" name="radio-set-1729796857-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796857-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796857-4" type="radio" name="radio-set-1729796857-3" class="tab-selector-2" /> <label for="tab-1729796857-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g = g.withComputer() ==>graphtraversalsource[tinkergraph[vertices:5 edges:5], graphcomputer] gremlin> g.V(1).shortestPath(). with(ShortestPath.edges, Direction.OUT). with(ShortestPath.target, hasId(5)) ==>[v[1],v[2],v[4],v[5]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g = g.withComputer() g.V(1).shortestPath(). with(ShortestPath.edges, Direction.OUT). with(ShortestPath.target, hasId(5))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The previous example defines the length of the path by the number of vertices in the path, but the "path" might also be measured by data within the graph itself. The following example use the same graph structure as the previous example, but includes a "weight" on the edges, that will be used to help determine the "cost" of a particular path: </div> <section class="tabs tabs-2"> <input id="tab-1729796857-5" type="radio" name="radio-set-1729796857-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796857-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796857-6" type="radio" name="radio-set-1729796857-5" class="tab-selector-2" /> <label for="tab-1729796857-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id, 1).as('1'). addV().property(id, 2).as('2'). addV().property(id, 3).as('3'). addV().property(id, 4).as('4'). addV().property(id, 5).as('5'). addE('knows').from('1').to('2').property('weight', 1.25). addE('knows').from('2').to('4').property('weight', 1.5). addE('knows').from('4').to('5').property('weight', 0.25). addE('knows').from('2').to('3').property('weight', 0.25). addE('knows').from('3').to('4').property('weight', 0.25).iterate() gremlin> g.V(1).repeat(out().simplePath()).until(hasId(5)).path(). group().by(count(local)).next() //// (1) ==>4=[path[v[1], v[2], v[4], v[5]]] ==>5=[path[v[1], v[2], v[3], v[4], v[5]]] gremlin> g.V(1).repeat(outE().inV().simplePath()).until(hasId(5)). path().by(coalesce(values('weight'), constant(0.0))). map(unfold().sum()) //// (2) ==>3.00 ==>2.00 gremlin> g.V(1).repeat(outE().inV().simplePath()).until(hasId(5)). path().by(constant(0.0)).by('weight').map(unfold().sum()) //// (3) ==>3.00 ==>2.00 gremlin> g.V(1).repeat(outE().inV().simplePath()).until(hasId(5)). path().as('p'). map(unfold().coalesce(values('weight'), constant(0.0)).sum()).as('cost'). select('cost','p') //// (4) ==>[cost:3.00,p:[v[1],e[0][1-knows->2],v[2],e[1][2-knows->4],v[4],e[2][4-knows->5],v[5]]] ==>[cost:2.00,p:[v[1],e[0][1-knows->2],v[2],e[3][2-knows->3],v[3],e[4][3-knows->4],v[4],e[2][4-knows->5],v[5]]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id, 1).as('1'). addV().property(id, 2).as('2'). addV().property(id, 3).as('3'). addV().property(id, 4).as('4'). addV().property(id, 5).as('5'). addE('knows').from('1').to('2').property('weight', 1.25). addE('knows').from('2').to('4').property('weight', 1.5). addE('knows').from('4').to('5').property('weight', 0.25). addE('knows').from('2').to('3').property('weight', 0.25). addE('knows').from('3').to('4').property('weight', 0.25).iterate() g.V(1).repeat(out().simplePath()).until(hasId(5)).path(). group().by(count(local)).next() //// (1) g.V(1).repeat(outE().inV().simplePath()).until(hasId(5)). path().by(coalesce(values('weight'), constant(0.0))). map(unfold().sum()) //// (2) g.V(1).repeat(outE().inV().simplePath()).until(hasId(5)). path().by(constant(0.0)).by('weight').map(unfold().sum()) //// (3) g.V(1).repeat(outE().inV().simplePath()).until(hasId(5)). path().as('p'). map(unfold().coalesce(values('weight'), constant(0.0)).sum()).as('cost'). select('cost','p') //4</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Note that the shortest path as determined by the structure of the graph is the same. </li> <li> Calculate the "cost" of the path as determined by the weight on the edges. As the "weight" data is on the edges between the vertices, it is necessary to change the contents of the <code>repeat</code> step to use <code>outE().inV()</code> so that the edge is included in the path. The path is then post-processed with a <code>by</code> modulator that extracts the "weight" value. The traversal uses <code>coalesce</code> as there is a mixture of vertices and edges in the path and the traversal is only interested in edge elements that can return a "weight" property. The final part of the traversal executes a map function over each path, unfolding it and summing the weights. </li> <li> The same traversal as the one above it, but avoids the use of <code>coalesce</code> with the use of two <code>by</code> modulators. The <code>by</code> modulator is applied in a round-robin fashion, so the first <code>by</code> will always apply to a vertex (as it is the first item in every path) and the second <code>by</code> will always apply to an edge (as it always follows the vertex in the path). </li> <li> The output of the previous examples of the "cost" wasn’t terribly useful as it didn’t include which path had the calculated cost. With some slight modifications given the use of <code>select</code> it becomes possible to include the path in the output. Note that the path with the lowest "cost" actually has a longer path length as determined by the graph structure. </li> </ol> </div> <div class="paragraph"> The next code block demonstrates how the <code>shortestPath()</code> step can be used in OLAP to determine the shortest weighted path. </div> <section class="tabs tabs-2"> <input id="tab-1729796857-7" type="radio" name="radio-set-1729796857-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796857-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796857-8" type="radio" name="radio-set-1729796857-7" class="tab-selector-2" /> <label for="tab-1729796857-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g = g.withComputer() ==>graphtraversalsource[tinkergraph[vertices:5 edges:5], graphcomputer] gremlin> g.V(1).shortestPath(). with(ShortestPath.edges, Direction.OUT). with(ShortestPath.distance, 'weight'). with(ShortestPath.target, hasId(5)) ==>[v[1],v[2],v[3],v[4],v[5]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g = g.withComputer() g.V(1).shortestPath(). with(ShortestPath.edges, Direction.OUT). with(ShortestPath.distance, 'weight'). with(ShortestPath.target, hasId(5))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The following query illustrates how <code>select(<traversal>)</code> can be used to find all shortest weighted undirected paths in the modern toy graph. </div> <section class="tabs tabs-2"> <input id="tab-1729796857-9" type="radio" name="radio-set-1729796857-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796857-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796857-10" type="radio" name="radio-set-1729796857-9" class="tab-selector-2" /> <label for="tab-1729796857-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSack(0.0).V().as("from"). //// (1) repeat(bothE(). sack(sum). by("weight"). otherV(). //// (2) where(neq("from")).as("to"). //// (3) group("m"). //// (4) by(select("from","to")). by(sack().min()). filter(project("s","x"). //// (5) by(sack()). by(select("m").select(select("from","to"))). where("s", eq("x"))). group("p"). //// (6) by(select("from", "to")). by(map(union(path().by("name").by("weight"), sack()).fold())). barrier()). cap("p").unfold(). order(). //// (7) by(select(keys).select("from").id()). by(select(keys).select("to").id()). barrier(). dedup(). //// (8) by(select(keys).select(values).order(local).by(id)) ==>{from=v[1], to=v[2]}=[path[marko, 0.5, vadas], 0.5] ==>{from=v[1], to=v[3]}=[path[marko, 0.4, lop], 0.4] ==>{from=v[1], to=v[4]}=[path[marko, 0.4, lop, 0.4, josh], 0.8] ==>{from=v[1], to=v[5]}=[path[marko, 0.4, lop, 0.4, josh, 1.0, ripple], 1.8] ==>{from=v[1], to=v[6]}=[path[marko, 0.4, lop, 0.2, peter], 0.6] ==>{from=v[2], to=v[3]}=[path[vadas, 0.5, marko, 0.4, lop], 0.9] ==>{from=v[2], to=v[4]}=[path[vadas, 0.5, marko, 0.4, lop, 0.4, josh], 1.3] ==>{from=v[2], to=v[5]}=[path[vadas, 0.5, marko, 0.4, lop, 0.4, josh, 1.0, ripple], 2.3] ==>{from=v[2], to=v[6]}=[path[vadas, 0.5, marko, 0.4, lop, 0.2, peter], 1.1] ==>{from=v[3], to=v[4]}=[path[lop, 0.4, josh], 0.4] ==>{from=v[3], to=v[5]}=[path[lop, 0.4, josh, 1.0, ripple], 1.4] ==>{from=v[3], to=v[6]}=[path[lop, 0.2, peter], 0.2] ==>{from=v[4], to=v[5]}=[path[josh, 1.0, ripple], 1.0] ==>{from=v[4], to=v[6]}=[path[josh, 0.4, lop, 0.2, peter], 0.6] ==>{from=v[5], to=v[6]}=[path[ripple, 1.0, josh, 0.4, lop, 0.2, peter], 1.6]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSack(0.0).V().as("from"). //// (1) repeat(bothE(). sack(sum). by("weight"). otherV(). //// (2) where(neq("from")).as("to"). //// (3) group("m"). //// (4) by(select("from","to")). by(sack().min()). filter(project("s","x"). //// (5) by(sack()). by(select("m").select(select("from","to"))). where("s", eq("x"))). group("p"). //// (6) by(select("from", "to")). by(map(union(path().by("name").by("weight"), sack()).fold())). barrier()). cap("p").unfold(). order(). //// (7) by(select(keys).select("from").id()). by(select(keys).select("to").id()). barrier(). dedup(). //// (8) by(select(keys).select(values).order(local).by(id))</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Start the traversal from all vertices with an initial sack value of 0. </li> <li> Traverse into all directions and sum up the edge weight values. </li> <li> Filter out the initial start vertex. </li> <li> For the current start and end vertex, update the minimum sack value (weighted length of the path). </li> <li> Compare the current weighted path length to the current minimum weighted path length between the 2 vertices. Eliminate traversers that found a path that is longer than the current shortest path. </li> <li> Update the path and weighted path length for the current start and end vertex pair. </li> <li> Order the output by the start vertex id and then the end vertex id (for better readability). </li> <li> Deduplicate vertex pairs (the shortest path from <code>v[1]</code> to <code>v[6]</code> is the same as the path from <code>v[6]</code> to <code>v[1]</code>). </li> </ol> </div> <div class="paragraph"> Again, this can be translated into an OLAP query using the <code>shortestPath()</code> step. </div> <section class="tabs tabs-2"> <input id="tab-1729796857-11" type="radio" name="radio-set-1729796857-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796857-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796857-12" type="radio" name="radio-set-1729796857-11" class="tab-selector-2" /> <label for="tab-1729796857-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> result = g.withComputer().V(). shortestPath(). with(ShortestPath.distance, 'weight'). with(ShortestPath.includeEdges, true). filter(count(local).is(gt(1))). group(). by(project('from','to'). by(limit(local, 1)). by(tail(local, 1))). unfold(). order(). by(select(keys).select('from').id()). by(select(keys).select('to').id()).toList() ==>{from=v[1], to=v[2]}=[path[v[1], e[7][1-knows->2], v[2]]] ==>{from=v[1], to=v[3]}=[path[v[1], e[9][1-created->3], v[3]]] ==>{from=v[1], to=v[4]}=[path[v[1], e[9][1-created->3], v[3], e[11][4-created->3], v[4]]] ==>{from=v[1], to=v[5]}=[path[v[1], e[9][1-created->3], v[3], e[11][4-created->3], v[4], e[10][4-created->5], v[5]]] ==>{from=v[1], to=v[6]}=[path[v[1], e[9][1-created->3], v[3], e[12][6-created->3], v[6]]] ==>{from=v[2], to=v[1]}=[path[v[2], e[7][1-knows->2], v[1]]] ==>{from=v[2], to=v[3]}=[path[v[2], e[7][1-knows->2], v[1], e[9][1-created->3], v[3]]] ==>{from=v[2], to=v[4]}=[path[v[2], e[7][1-knows->2], v[1], e[9][1-created->3], v[3], e[11][4-created->3], v[4]]] ==>{from=v[2], to=v[5]}=[path[v[2], e[7][1-knows->2], v[1], e[9][1-created->3], v[3], e[11][4-created->3], v[4], e[10][4-created->5], v[5]]] ==>{from=v[2], to=v[6]}=[path[v[2], e[7][1-knows->2], v[1], e[9][1-created->3], v[3], e[12][6-created->3], v[6]]] ==>{from=v[3], to=v[1]}=[path[v[3], e[9][1-created->3], v[1]]] ==>{from=v[3], to=v[2]}=[path[v[3], e[9][1-created->3], v[1], e[7][1-knows->2], v[2]]] ==>{from=v[3], to=v[4]}=[path[v[3], e[11][4-created->3], v[4]]] ==>{from=v[3], to=v[5]}=[path[v[3], e[11][4-created->3], v[4], e[10][4-created->5], v[5]]] ==>{from=v[3], to=v[6]}=[path[v[3], e[12][6-created->3], v[6]]] ==>{from=v[4], to=v[1]}=[path[v[4], e[11][4-created->3], v[3], e[9][1-created->3], v[1]]] ==>{from=v[4], to=v[2]}=[path[v[4], e[11][4-created->3], v[3], e[9][1-created->3], v[1], e[7][1-knows->2], v[2]]] ==>{from=v[4], to=v[3]}=[path[v[4], e[11][4-created->3], v[3]]] ==>{from=v[4], to=v[5]}=[path[v[4], e[10][4-created->5], v[5]]] ==>{from=v[4], to=v[6]}=[path[v[4], e[11][4-created->3], v[3], e[12][6-created->3], v[6]]] ==>{from=v[5], to=v[1]}=[path[v[5], e[10][4-created->5], v[4], e[11][4-created->3], v[3], e[9][1-created->3], v[1]]] ==>{from=v[5], to=v[2]}=[path[v[5], e[10][4-created->5], v[4], e[11][4-created->3], v[3], e[9][1-created->3], v[1], e[7][1-knows->2], v[2]]] ==>{from=v[5], to=v[3]}=[path[v[5], e[10][4-created->5], v[4], e[11][4-created->3], v[3]]] ==>{from=v[5], to=v[4]}=[path[v[5], e[10][4-created->5], v[4]]] ==>{from=v[5], to=v[6]}=[path[v[5], e[10][4-created->5], v[4], e[11][4-created->3], v[3], e[12][6-created->3], v[6]]] ==>{from=v[6], to=v[1]}=[path[v[6], e[12][6-created->3], v[3], e[9][1-created->3], v[1]]] ==>{from=v[6], to=v[2]}=[path[v[6], e[12][6-created->3], v[3], e[9][1-created->3], v[1], e[7][1-knows->2], v[2]]] ==>{from=v[6], to=v[3]}=[path[v[6], e[12][6-created->3], v[3]]] ==>{from=v[6], to=v[4]}=[path[v[6], e[12][6-created->3], v[3], e[11][4-created->3], v[4]]] ==>{from=v[6], to=v[5]}=[path[v[6], e[12][6-created->3], v[3], e[11][4-created->3], v[4], e[10][4-created->5], v[5]]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">result = g.withComputer().V(). shortestPath(). with(ShortestPath.distance, 'weight'). with(ShortestPath.includeEdges, true). filter(count(local).is(gt(1))). group(). by(project('from','to'). by(limit(local, 1)). by(tail(local, 1))). unfold(). order(). by(select(keys).select('from').id()). by(select(keys).select('to').id()).toList()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The obvious difference in the result is the absence of property values in the OLAP result. Since OLAP traversers are not allowed to leave the local star graph, it’s not possible to have the exact same result in an OLAP query. However, the determined shortest paths can be passed back into the OLTP <code>GraphTraversalSource</code>, which can then be used to query the values. </div> <section class="tabs tabs-2"> <input id="tab-1729796857-13" type="radio" name="radio-set-1729796857-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796857-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796857-14" type="radio" name="radio-set-1729796857-13" class="tab-selector-2" /> <label for="tab-1729796857-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSideEffect('v', []). //// (1) inject(result.toArray()).as('kv').select(values). unfold(). map(unfold().as('v_or_e'). coalesce(V().where(eq('v_or_e')).aggregate(local,'v'), select('v').tail(local, 1).bothE().where(eq('v_or_e'))). values('name','weight'). fold()). group(). by(select('kv').select(keys)).unfold(). order(). by(select(keys).select('from').id()). by(select(keys).select('to').id()).toList() ==>{from=v[1], to=v[2]}=[[marko, 0.5, vadas]] ==>{from=v[1], to=v[3]}=[[marko, 0.4, lop]] ==>{from=v[1], to=v[4]}=[[marko, 0.4, lop, 0.4, josh]] ==>{from=v[1], to=v[5]}=[[marko, 0.4, lop, 0.4, josh, 1.0, ripple]] ==>{from=v[1], to=v[6]}=[[marko, 0.4, lop, 0.2, peter]] ==>{from=v[2], to=v[1]}=[[vadas, 0.5, marko]] ==>{from=v[2], to=v[3]}=[[vadas, 0.5, marko, 0.4, lop]] ==>{from=v[2], to=v[4]}=[[vadas, 0.5, marko, 0.4, lop, 0.4, josh]] ==>{from=v[2], to=v[5]}=[[vadas, 0.5, marko, 0.4, lop, 0.4, josh, 1.0, ripple]] ==>{from=v[2], to=v[6]}=[[vadas, 0.5, marko, 0.4, lop, 0.2, peter]] ==>{from=v[3], to=v[1]}=[[lop, 0.4, marko]] ==>{from=v[3], to=v[2]}=[[lop, 0.4, marko, 0.5, vadas]] ==>{from=v[3], to=v[4]}=[[lop, 0.4, josh]] ==>{from=v[3], to=v[5]}=[[lop, 0.4, josh, 1.0, ripple]] ==>{from=v[3], to=v[6]}=[[lop, 0.2, peter]] ==>{from=v[4], to=v[1]}=[[josh, 0.4, lop, 0.4, marko]] ==>{from=v[4], to=v[2]}=[[josh, 0.4, lop, 0.4, marko, 0.5, vadas]] ==>{from=v[4], to=v[3]}=[[josh, 0.4, lop]] ==>{from=v[4], to=v[5]}=[[josh, 1.0, ripple]] ==>{from=v[4], to=v[6]}=[[josh, 0.4, lop, 0.2, peter]] ==>{from=v[5], to=v[1]}=[[ripple, 1.0, josh, 0.4, lop, 0.4, marko]] ==>{from=v[5], to=v[2]}=[[ripple, 1.0, josh, 0.4, lop, 0.4, marko, 0.5, vadas]] ==>{from=v[5], to=v[3]}=[[ripple, 1.0, josh, 0.4, lop]] ==>{from=v[5], to=v[4]}=[[ripple, 1.0, josh]] ==>{from=v[5], to=v[6]}=[[ripple, 1.0, josh, 0.4, lop, 0.2, peter]] ==>{from=v[6], to=v[1]}=[[peter, 0.2, lop, 0.4, marko]] ==>{from=v[6], to=v[2]}=[[peter, 0.2, lop, 0.4, marko, 0.5, vadas]] ==>{from=v[6], to=v[3]}=[[peter, 0.2, lop]] ==>{from=v[6], to=v[4]}=[[peter, 0.2, lop, 0.4, josh]] ==>{from=v[6], to=v[5]}=[[peter, 0.2, lop, 0.4, josh, 1.0, ripple]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSideEffect('v', []). //// (1) inject(result.toArray()).as('kv').select(values). unfold(). map(unfold().as('v_or_e'). coalesce(V().where(eq('v_or_e')).aggregate(local,'v'), select('v').tail(local, 1).bothE().where(eq('v_or_e'))). values('name','weight'). fold()). group(). by(select('kv').select(keys)).unfold(). order(). by(select(keys).select('from').id()). by(select(keys).select('to').id()).toList()</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The side-effect <code>v</code> is used to keep track of the last processed vertex, hence it needs to be an order-preserving list. Without this explicit definition <code>v</code> would become a <code>BulkSet</code> which doesn’t preserve the insert order. </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="traversal-induced-values">Traversal Induced Values</h2> <div class="sectionbody"> <div class="paragraph"> The parameters of a <code>Traversal</code> can be known ahead of time as constants or might otherwise be passed in as dynamic arguments. </div> <section class="tabs tabs-2"> <input id="tab-1729796869-1" type="radio" name="radio-set-1729796869-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-2" type="radio" name="radio-set-1729796869-1" class="tab-selector-2" /> <label for="tab-1729796869-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko').out('knows').has('age', gt(29)).values('name') ==>josh</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko').out('knows').has('age', gt(29)).values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> In plain language, the above Gremlin asks, "What are the names of the people who Marko knows who are over the age of 29?". In this case, "29" is known as a constant to the traversal. Of course, if the question is changed slightly to instead ask, "What are the names of the people who Marko knows who are older than he is?", the hardcoding of "29" will no longer suffice. There are multiple ways Gremlin would allow this second question to be answered. The first is obvious to any programmer - use a variable: </div> <section class="tabs tabs-2"> <input id="tab-1729796869-3" type="radio" name="radio-set-1729796869-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-4" type="radio" name="radio-set-1729796869-3" class="tab-selector-2" /> <label for="tab-1729796869-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> vMarko = g.V().has('name','marko').next() ==>v[1] gremlin> g.V(vMarko).out('knows').has('age', gt(marko.value('age'))).values('name') ==>josh</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">vMarko = g.V().has('name','marko').next() g.V(vMarko).out('knows').has('age', gt(marko.value('age'))).values('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The downside to this approach is that it takes two separate traversals to answer the question. Ideally, there should be a single traversal, that can query "marko" once, determine his <code>age</code> and then use that for the value supplied to filter the people he knows. In this way the value for the <code>age</code> in the <code>has()</code>-filter is induced from the <code>Traversal</code> itself. </div> <section class="tabs tabs-2"> <input id="tab-1729796869-5" type="radio" name="radio-set-1729796869-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-6" type="radio" name="radio-set-1729796869-5" class="tab-selector-2" /> <label for="tab-1729796869-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko').as('marko'). //// (1) out('knows').as('friend'). //// (2) where('friend', gt('marko')).by('age'). //// (3) values('name') //// (4) ==>josh</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko').as('marko'). //// (1) out('knows').as('friend'). //// (2) where('friend', gt('marko')).by('age'). //// (3) values('name') //4</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Find the "marko" <code>Vertex</code> and label it as "marko". </li> <li> Traverse out on the "knows" edges to the adjacent <code>Vertex</code> and label it as "friend". </li> <li> Continue to traverser only if Marko’s current friend is older than him. </li> <li> Get the name of Marko’s older friend. </li> </ol> </div> <div class="paragraph"> As another example of how traversal induced values can be used, consider a scenario where there was a graph that contained people, their friendship relationships, and the movies that they liked. </div> <div class="paragraph"> <img src="../images/traversal-induced-values-3.png" alt="traversal induced values 3" width="600"> </div> <section class="tabs tabs-2"> <input id="tab-1729796869-7" type="radio" name="radio-set-1729796869-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-8" type="radio" name="radio-set-1729796869-7" class="tab-selector-2" /> <label for="tab-1729796869-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV("user").property("name", "alice").as("u1"). addV("user").property("name", "jen").as("u2"). addV("user").property("name", "dave").as("u3"). addV("movie").property("name", "the wild bunch").as("m1"). addV("movie").property("name", "young guns").as("m2"). addV("movie").property("name", "unforgiven").as("m3"). addE("friend").from("u1").to("u2"). addE("friend").from("u1").to("u3"). addE("like").from("u2").to("m1"). addE("like").from("u2").to("m2"). addE("like").from("u3").to("m2"). addE("like").from("u3").to("m3").iterate()</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV("user").property("name", "alice").as("u1"). addV("user").property("name", "jen").as("u2"). addV("user").property("name", "dave").as("u3"). addV("movie").property("name", "the wild bunch").as("m1"). addV("movie").property("name", "young guns").as("m2"). addV("movie").property("name", "unforgiven").as("m3"). addE("friend").from("u1").to("u2"). addE("friend").from("u1").to("u3"). addE("like").from("u2").to("m1"). addE("like").from("u2").to("m2"). addE("like").from("u3").to("m2"). addE("like").from("u3").to("m3").iterate()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Getting a list of all the movies that Alice’s friends like could be done like this: </div> <section class="tabs tabs-2"> <input id="tab-1729796869-9" type="radio" name="radio-set-1729796869-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-10" type="radio" name="radio-set-1729796869-9" class="tab-selector-2" /> <label for="tab-1729796869-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','alice').out("friend").out("like").values("name") ==>the wild bunch ==>young guns ==>young guns ==>unforgiven</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','alice').out("friend").out("like").values("name")</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> but what if there was a need to get a list of movies that all her Alice’s friends liked. In this case, that would mean filtering out "the wild bunch" and "unforgiven". </div> <section class="tabs tabs-2"> <input id="tab-1729796869-11" type="radio" name="radio-set-1729796869-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-12" type="radio" name="radio-set-1729796869-11" class="tab-selector-2" /> <label for="tab-1729796869-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("name","alice"). out("friend").aggregate("friends"). //// (1) out("like").dedup(). //// (2) filter(__.in("like").where(within("friends")).count().as("a"). //// (3) select("friends").count(local).where(eq("a"))). //// (4) values("name") ==>young guns</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("name","alice"). out("friend").aggregate("friends"). //// (1) out("like").dedup(). //// (2) filter(__.in("like").where(within("friends")).count().as("a"). //// (3) select("friends").count(local).where(eq("a"))). //// (4) values("name")</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Gather Alice’s list of friends to a list called "friends". </li> <li> Traverse to the unique list of movies that Alice’s friends like. </li> <li> Remove movies that weren’t liked by all friends. This starts by taking each movie and traversing back in on the "like" edges to friends who liked the movie (note the use of <code>where(within("friends"))</code> to limit those likes to only Alice’s friends as aggregated in step one) and count them up into "a". </li> <li> Count the aggregated friends and see if the number matches what was stored in "a" which would mean that all friends like the movie. </li> </ol> </div> <div class="paragraph"> Traversal induced values are not just for filtering. They can also be used when writing the values of the properties of one <code>Vertex</code> to another: </div> <section class="tabs tabs-2"> <input id="tab-1729796869-13" type="radio" name="radio-set-1729796869-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-14" type="radio" name="radio-set-1729796869-13" class="tab-selector-2" /> <label for="tab-1729796869-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name', 'marko').as('marko'). out('created').property('creator', select('marko').by('name')) ==>v[3] gremlin> g.V().has('name', 'marko').out('created').elementMap() ==>[id:3,label:software,creator:marko,name:lop,lang:java]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name', 'marko').as('marko'). out('created').property('creator', select('marko').by('name')) g.V().has('name', 'marko').out('created').elementMap()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> In a more complex example of how this might work, consider a situation where the goal is to propagate a value stored on a particular vertex through one of more additional connected vertices using some value on the connecting edges to determine the value to assign. For example, the following graph depicts three "tank" vertices where the edges represent the direction a particular "tank" should drain and the "factor" by which it should do it: </div> <div class="paragraph"> <img src="../images/traversal-induced-values-1.png" alt="traversal induced values 1" width="700"> </div> <div class="paragraph"> If the traversal started at tank "a", then the value of "amount" on that tank would be used to calculate what the value of tank "b" was by multiplying it by the value of the "factor" property on the edge between vertices "a" and "b". In this case the amount of tank "b" would then be 50. Following this pattern, when going from tank "b" to tank "c", the value of the "amount" of tank "c" would be 5. </div> <div class="paragraph"> <img src="../images/traversal-induced-values-2.png" alt="traversal induced values 2" width="700"> </div> <div class="paragraph"> Using Gremlin <code>sack()</code>, this kind of operation could be specified as a single traversal: </div> <section class="tabs tabs-2"> <input id="tab-1729796869-15" type="radio" name="radio-set-1729796869-15" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-15" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-16" type="radio" name="radio-set-1729796869-15" class="tab-selector-2" /> <label for="tab-1729796869-16" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV('tank').property('name', 'a').property('amount', 100.0).as('a'). addV('tank').property('name', 'b').property('amount', 0.0).as('b'). addV('tank').property('name', 'c').property('amount', 0.0).as('c'). addE('drain').property('factor', 0.5).from('a').to('b'). addE('drain').property('factor', 0.1).from('b').to('c').iterate() gremlin> vA = g.V().has('name','a').next() ==>v[0] gremlin> g.withSack(vA.value('amount')). V(vA).repeat(outE('drain').sack(mult).by('factor'). inV().property('amount', sack())). until(__.outE('drain').count().is(0)).iterate() gremlin> g.V().elementMap() ==>[id:0,label:tank,amount:100.0,name:a] ==>[id:3,label:tank,amount:50.00,name:b] ==>[id:6,label:tank,amount:5.000,name:c]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV('tank').property('name', 'a').property('amount', 100.0).as('a'). addV('tank').property('name', 'b').property('amount', 0.0).as('b'). addV('tank').property('name', 'c').property('amount', 0.0).as('c'). addE('drain').property('factor', 0.5).from('a').to('b'). addE('drain').property('factor', 0.1).from('b').to('c').iterate() vA = g.V().has('name','a').next() g.withSack(vA.value('amount')). V(vA).repeat(outE('drain').sack(mult).by('factor'). inV().property('amount', sack())). until(__.outE('drain').count().is(0)).iterate() g.V().elementMap()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The "sack value" gets initialized to the value of tank "a". The traversal iteratively traverses out on the "drain" edges and uses <code>mult</code> to multiply the sack value by the value of "factor". The sack value at that point is then written to the "amount" of the current vertex. </div> <div class="paragraph"> As shown in the previous example, <code>sack()</code> is a useful way to "carry" and manipulate a value that can be later used elsewhere in the traversal. Here is another example of its usage where it is utilized to increment all the "age" values in the modern toy graph by 10: </div> <section class="tabs tabs-2"> <input id="tab-1729796869-17" type="radio" name="radio-set-1729796869-17" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-17" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-18" type="radio" name="radio-set-1729796869-17" class="tab-selector-2" /> <label for="tab-1729796869-18" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSack(0).V().has("age"). sack(assign).by("age").sack(sum).by(constant(10)). property("age", sack()).elementMap() ==>[id:1,label:person,name:marko,age:39] ==>[id:2,label:person,name:vadas,age:37] ==>[id:4,label:person,name:josh,age:42] ==>[id:6,label:person,name:peter,age:45]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSack(0).V().has("age"). sack(assign).by("age").sack(sum).by(constant(10)). property("age", sack()).elementMap()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> In the above case, the sack is initialized to zero and as each vertex is iterated, the "age" is assigned to the sack with <code>sack(assign).by('age')</code>. That value in the sack is then incremented by the value <code>constant(10)</code> and assigned to the "age" property of the same vertex. </div> <div class="paragraph"> This value the sack is incremented by need not be a constant. It could also be derived from the traversal itself. Using the same example, the "weight" property on the incident edges will be used as the value to add to the sack: </div> <section class="tabs tabs-2"> <input id="tab-1729796869-19" type="radio" name="radio-set-1729796869-19" class="tab-selector-1" checked="checked" /> <label for="tab-1729796869-19" class="tab-label-1">console (groovy)</label> <input id="tab-1729796869-20" type="radio" name="radio-set-1729796869-19" class="tab-selector-2" /> <label for="tab-1729796869-20" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSack(0).V().has("age"). sack(assign).by("age").sack(sum).by(bothE().values("weight").sum()). property("age", sack()).elementMap() ==>[id:1,label:person,name:marko,age:30.9] ==>[id:2,label:person,name:vadas,age:27.5] ==>[id:4,label:person,name:josh,age:34.4] ==>[id:6,label:person,name:peter,age:35.2]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSack(0).V().has("age"). sack(assign).by("age").sack(sum).by(bothE().values("weight").sum()). property("age", sack()).elementMap()</code></pre> </div> </div> </div> </div> </section> </div> </div> <div class="sect1"> <h2 id="tree">Tree</h2> <div class="sectionbody"> <div class="paragraph"> <img src="../images/gremlin-tree.png" alt="gremlin tree" width="280"> </div> <div class="sect2"> <h3 id="_lowest_common_ancestor">Lowest Common Ancestor</h3> <div class="paragraph"> <img src="../images/tree-lca.png" alt="tree lca" width="230"> Given a tree, the <a href="https://en.wikipedia.org/wiki/Lowest_common_ancestor">lowest common ancestor</a> is the deepest vertex that is common to two or more other vertices. The diagram to the right depicts the common ancestor tree for vertices A and D in the various green shades. The C vertex, the vertex with the darkest green shading, is the lowest common ancestor. </div> <div class="paragraph"> The following code simply sets up the graph depicted above using "hasParent" for the edge label: </div> <section class="tabs tabs-2"> <input id="tab-1729796882-1" type="radio" name="radio-set-1729796882-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-2" type="radio" name="radio-set-1729796882-1" class="tab-selector-2" /> <label for="tab-1729796882-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id, 'A').as('a'). addV().property(id, 'B').as('b'). addV().property(id, 'C').as('c'). addV().property(id, 'D').as('d'). addV().property(id, 'E').as('e'). addV().property(id, 'F').as('f'). addV().property(id, 'G').as('g'). addE('hasParent').from('a').to('b'). addE('hasParent').from('b').to('c'). addE('hasParent').from('d').to('c'). addE('hasParent').from('c').to('e'). addE('hasParent').from('e').to('f'). addE('hasParent').from('g').to('f').iterate()</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id, 'A').as('a'). addV().property(id, 'B').as('b'). addV().property(id, 'C').as('c'). addV().property(id, 'D').as('d'). addV().property(id, 'E').as('e'). addV().property(id, 'F').as('f'). addV().property(id, 'G').as('g'). addE('hasParent').from('a').to('b'). addE('hasParent').from('b').to('c'). addE('hasParent').from('d').to('c'). addE('hasParent').from('c').to('e'). addE('hasParent').from('e').to('f'). addE('hasParent').from('g').to('f').iterate()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Given that graph, the following traversal will get the lowest common ancestor for two vertices, A and D: </div> <section class="tabs tabs-2"> <input id="tab-1729796882-3" type="radio" name="radio-set-1729796882-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-4" type="radio" name="radio-set-1729796882-3" class="tab-selector-2" /> <label for="tab-1729796882-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V('A'). repeat(out('hasParent')).emit().as('x'). repeat(__.in('hasParent')).emit(hasId('D')). select('x').limit(1) ==>v[C]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V('A'). repeat(out('hasParent')).emit().as('x'). repeat(__.in('hasParent')).emit(hasId('D')). select('x').limit(1)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The above traversal is reasonably straightforward to follow in that it simply traverses up the tree from the A vertex and then traverses down from each ancestor until it finds the "D" vertex. The first path that uncovers that match is the lowest common ancestor. </div> <div class="paragraph"> The complexity of finding the lowest common ancestor increases when trying to find the ancestors of three or more vertices. </div> <section class="tabs tabs-2"> <input id="tab-1729796882-5" type="radio" name="radio-set-1729796882-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-6" type="radio" name="radio-set-1729796882-5" class="tab-selector-2" /> <label for="tab-1729796882-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> input = ['A','B','D'] ==>A ==>B ==>D gremlin> g.V(input.head()). repeat(out('hasParent')).emit().as('x'). //// (1) V().has(id, within(input.tail())). //// (2) repeat(out('hasParent')).emit(where(eq('x'))). //// (3) group(). by(select('x')). by(path().count(local).fold()). //// (4) unfold().filter(select(values).count(local).is(input.tail().size())). //// (5) order().by(select(values). unfold().sum()). //// (6) select(keys).limit(1) //// (7) ==>v[C]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">input = ['A','B','D'] g.V(input.head()). repeat(out('hasParent')).emit().as('x'). //// (1) V().has(id, within(input.tail())). //// (2) repeat(out('hasParent')).emit(where(eq('x'))). //// (3) group(). by(select('x')). by(path().count(local).fold()). //// (4) unfold().filter(select(values).count(local).is(input.tail().size())). //// (5) order().by(select(values). unfold().sum()). //// (6) select(keys).limit(1) //7</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The start of the traversal is not so different than the previous one and starts with vertex A. </li> <li> Use a mid-traversal <code>V()</code> to find the child vertices B and D. </li> <li> Traverse up the tree for B and D and find common ancestors that were labeled with "x". </li> <li> Group on the common ancestors where the value of the grouping is the length of the path. </li> <li> The result of the previous step is a <code>Map</code> with a vertex (i.e. common ancestor) for the key and a list of path lengths. Unroll the <code>Map</code> and ensure that the number of path lengths are equivalent to the number of children that were given to the mid-traversal <code>V()</code>. </li> <li> Order the results based on the sum of the path lengths. </li> <li> Since the results were placed in ascending order, the first result must be the lowest common ancestor. </li> </ol> </div> <div class="paragraph"> As the above traversal utilizes a mid-traversal <code>V()</code>, it cannot be used for OLAP. In OLAP, the pattern changes a bit: </div> <section class="tabs tabs-2"> <input id="tab-1729796882-7" type="radio" name="radio-set-1729796882-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-8" type="radio" name="radio-set-1729796882-7" class="tab-selector-2" /> <label for="tab-1729796882-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withComputer(). V().has(id, within(input)). aggregate('input').hasId(input.head()). //// (1) repeat(out('hasParent')).emit().as('x'). select('input').unfold().has(id, within(input.tail())). repeat(out('hasParent')).emit(where(eq('x'))). group(). by(select('x')). by(path().count(local).fold()). unfold().filter(select(values).count(local).is(input.tail().size())). order(). by(select(values).unfold().sum()). select(keys).limit(1) ==>v[C]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withComputer(). V().has(id, within(input)). aggregate('input').hasId(input.head()). //// (1) repeat(out('hasParent')).emit().as('x'). select('input').unfold().has(id, within(input.tail())). repeat(out('hasParent')).emit(where(eq('x'))). group(). by(select('x')). by(path().count(local).fold()). unfold().filter(select(values).count(local).is(input.tail().size())). order(). by(select(values).unfold().sum()). select(keys).limit(1)</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The main difference for OLAP is the use of <code>aggregate()</code> over the mid-traversal <code>V()</code>. </li> </ol> </div> </div> <div class="sect2"> <h3 id="_maximum_depth">Maximum Depth</h3> <div class="paragraph"> Finding the maximum depth of a tree starting from a specified root vertex can be determined as follows: </div> <section class="tabs tabs-2"> <input id="tab-1729796882-9" type="radio" name="radio-set-1729796882-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-10" type="radio" name="radio-set-1729796882-9" class="tab-selector-2" /> <label for="tab-1729796882-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property('name', 'A').as('a'). addV().property('name', 'B').as('b'). addV().property('name', 'C').as('c'). addV().property('name', 'D').as('d'). addV().property('name', 'E').as('e'). addV().property('name', 'F').as('f'). addV().property('name', 'G').as('g'). addE('hasParent').from('a').to('b'). addE('hasParent').from('b').to('c'). addE('hasParent').from('d').to('c'). addE('hasParent').from('c').to('e'). addE('hasParent').from('e').to('f'). addE('hasParent').from('g').to('f').iterate() gremlin> g.V().has('name','F').repeat(__.in()).emit().path().count(local).max() ==>5 gremlin> g.V().has('name','C').repeat(__.in()).emit().path().count(local).max() ==>3</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property('name', 'A').as('a'). addV().property('name', 'B').as('b'). addV().property('name', 'C').as('c'). addV().property('name', 'D').as('d'). addV().property('name', 'E').as('e'). addV().property('name', 'F').as('f'). addV().property('name', 'G').as('g'). addE('hasParent').from('a').to('b'). addE('hasParent').from('b').to('c'). addE('hasParent').from('d').to('c'). addE('hasParent').from('c').to('e'). addE('hasParent').from('e').to('f'). addE('hasParent').from('g').to('f').iterate() g.V().has('name','F').repeat(__.in()).emit().path().count(local).max() g.V().has('name','C').repeat(__.in()).emit().path().count(local).max()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> <img src="../images/gremlin-max-depth.png" alt="gremlin max depth" width="350">The traversals shown above are fairly straightforward. The traversal beings at a particular starting vertex, traverse in on the "hasParent" edges emitting all vertices as it goes. It calculates the path length and then selects the longest one. While this approach is quite direct, there is room for improvement: </div> <section class="tabs tabs-2"> <input id="tab-1729796882-11" type="radio" name="radio-set-1729796882-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-12" type="radio" name="radio-set-1729796882-11" class="tab-selector-2" /> <label for="tab-1729796882-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','F'). repeat(__.in()).emit(__.not(inE())).tail(1). path().count(local) ==>5 gremlin> g.V().has('name','C'). repeat(__.in()).emit(__.not(inE())).tail(1). path().count(local) ==>3</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','F'). repeat(__.in()).emit(__.not(inE())).tail(1). path().count(local) g.V().has('name','C'). repeat(__.in()).emit(__.not(inE())).tail(1). path().count(local)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> There are two optimizations at play. First, there is no need to emit all the vertices, only the "leaf" vertices (i.e. those without incoming edges). Second, all results save the last one can be ignored to that point (i.e. the last one is the one at the deepest point in the tree). In this way, the path and path length only need to be calculated for a single result. </div> <div class="paragraph"> The previous approaches to calculating the maximum depth use path calculations to achieve the answer. Path calculations can be expensive and if possible avoided if they are not needed. Another way to express a traversal that calculates the maximum depth is to use the <code>sack()</code>-step: </div> <section class="tabs tabs-2"> <input id="tab-1729796882-13" type="radio" name="radio-set-1729796882-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-14" type="radio" name="radio-set-1729796882-13" class="tab-selector-2" /> <label for="tab-1729796882-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSack(1).V().has('name','F'). repeat(__.in().sack(sum).by(constant(1))).emit(). sack().max() ==>5 gremlin> g.withSack(1).V().has('name','C'). repeat(__.in().sack(sum).by(constant(1))).emit(). sack().max() ==>3</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSack(1).V().has('name','F'). repeat(__.in().sack(sum).by(constant(1))).emit(). sack().max() g.withSack(1).V().has('name','C'). repeat(__.in().sack(sum).by(constant(1))).emit(). sack().max()</code></pre> </div> </div> </div> </div> </section> </div> <div class="sect2"> <h3 id="_time_based_indexing">Time-based Indexing</h3> <div class="paragraph"> Trees can be used for modeling time-oriented data in a graph. Modeling time where there are "year", "month" and "day" vertices (or lower granularity as needed) allows the structure of the graph to inherently index data tied to them. </div> <div class="paragraph"> <img src="../images/gremlin-index-time.png" alt="gremlin index time" width="800"> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> This model is discussed further in this Neo4j <a href="https://neo4j.com/blog/modeling-a-multilevel-index-in-neoj4/">blog post</a>. Also, there can be other versions of this model that utilize different edge/vertex labeling and property naming strategies. The schema depicted here is designed for simplicity. </td> </tr> </table> </div> <div class="paragraph"> The Gremlin script below creates the graph depicted in the graph above: </div> <section class="tabs tabs-2"> <input id="tab-1729796882-15" type="radio" name="radio-set-1729796882-15" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-15" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-16" type="radio" name="radio-set-1729796882-15" class="tab-selector-2" /> <label for="tab-1729796882-16" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV('year').property('name', '2016').as('y2016'). addV('month').property('name', 'may').as('m05'). addV('month').property('name', 'june').as('m06'). addV('day').property('name', '30').as('d30'). addV('day').property('name', '31').as('d31'). addV('day').property('name', '01').as('d01'). addV('event').property('name', 'A').as('eA'). addV('event').property('name', 'B').as('eB'). addV('event').property('name', 'C').as('eC'). addV('event').property('name', 'D').as('eD'). addV('event').property('name', 'E').as('eE'). addE('may').from('y2016').to('m05'). addE('june').from('y2016').to('m06'). addE('day30').from('m05').to('d30'). addE('day31').from('m05').to('d31'). addE('day01').from('m06').to('d01'). addE('has').from('d30').to('eA'). addE('has').from('d30').to('eB'). addE('has').from('d31').to('eC'). addE('has').from('d31').to('eD'). addE('has').from('d01').to('eE'). addE('next').from('d30').to('d31'). addE('next').from('d31').to('d01'). addE('next').from('m05').to('m06').iterate()</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV('year').property('name', '2016').as('y2016'). addV('month').property('name', 'may').as('m05'). addV('month').property('name', 'june').as('m06'). addV('day').property('name', '30').as('d30'). addV('day').property('name', '31').as('d31'). addV('day').property('name', '01').as('d01'). addV('event').property('name', 'A').as('eA'). addV('event').property('name', 'B').as('eB'). addV('event').property('name', 'C').as('eC'). addV('event').property('name', 'D').as('eD'). addV('event').property('name', 'E').as('eE'). addE('may').from('y2016').to('m05'). addE('june').from('y2016').to('m06'). addE('day30').from('m05').to('d30'). addE('day31').from('m05').to('d31'). addE('day01').from('m06').to('d01'). addE('has').from('d30').to('eA'). addE('has').from('d30').to('eB'). addE('has').from('d31').to('eC'). addE('has').from('d31').to('eD'). addE('has').from('d01').to('eE'). addE('next').from('d30').to('d31'). addE('next').from('d31').to('d01'). addE('next').from('m05').to('m06').iterate()</code></pre> </div> </div> </div> </div> </section> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <div class="title">Important</div> </td> <td class="content"> The code example above does not create any indices. Proper index creation, which is specific to the graph implementation used, will be critical to the performance of traversals over this structure. </td> </tr> </table> </div> <section class="tabs tabs-2"> <input id="tab-1729796882-17" type="radio" name="radio-set-1729796882-17" class="tab-selector-1" checked="checked" /> <label for="tab-1729796882-17" class="tab-label-1">console (groovy)</label> <input id="tab-1729796882-18" type="radio" name="radio-set-1729796882-17" class="tab-selector-2" /> <label for="tab-1729796882-18" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','2016').out().out().out('has').values() //// (1) ==>E ==>C ==>D ==>A ==>B gremlin> g.V().has('name','2016').out('may').out().out('has').values() //// (2) ==>C ==>D ==>A ==>B gremlin> g.V().has('name','2016').out('may').out('day31').out('has').values() //// (3) ==>C ==>D gremlin> g.V().has('name','2016').out('may').out('day31').as('start'). V().has('name','2016').out('june').out('day01').as('end'). emit().repeat(__.in('next')).until(where(eq('start'))). out('has'). order().by('name').values('name') //// (4) ==>C ==>D ==>E</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','2016').out().out().out('has').values() //// (1) g.V().has('name','2016').out('may').out().out('has').values() //// (2) g.V().has('name','2016').out('may').out('day31').out('has').values() //// (3) g.V().has('name','2016').out('may').out('day31').as('start'). V().has('name','2016').out('june').out('day01').as('end'). emit().repeat(__.in('next')).until(where(eq('start'))). out('has'). order().by('name').values('name') //4</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Find all the events in 2016. </li> <li> Find all the events in May of 2016. </li> <li> Find all the events on May 31, 2016. </li> <li> Find all the events between May 31, 2016 and June 1, 2016. </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="olap-spark-yarn">OLAP traversals with Spark on YARN</h2> <div class="sectionbody"> <div class="paragraph"> TinkerPop’s combination of <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#sparkgraphcomputer">SparkGraphComputer</a> and <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#_properties_files">HadoopGraph</a> allows for running distributed, analytical graph queries (OLAP) on a computer cluster. The <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#sparkgraphcomputer">reference documentation</a> covers the cases where Spark runs locally or where the cluster is managed by a Spark server. However, many users can only run OLAP jobs via the <a href="http://hadoop.apache.org/">Hadoop 3.x</a> Resource Manager (YARN), which requires <code>SparkGraphComputer</code> to be configured differently. This recipe describes this configuration. </div> <div class="sect2"> <h3 id="_approach">Approach</h3> <div class="paragraph"> Most configuration problems of TinkerPop with Spark on YARN stem from three reasons: </div> <div class="olist arabic"> <ol class="arabic"> <li> <code>SparkGraphComputer</code> creates its own <code>SparkContext</code> so it does not get any configs from the usual <code>spark-submit</code> command. </li> <li> The TinkerPop Spark plugin did not include Spark on YARN runtime dependencies until version 3.2.7/3.3.1. </li> <li> Resolving reason 2 by adding the cluster’s Spark jars to the classpath may create all kinds of version conflicts with the TinkerPop dependencies. </li> </ol> </div> <div class="paragraph"> The current recipe follows a minimalist approach in which no dependencies are added to the dependencies included in the TinkerPop binary distribution. The Hadoop cluster’s Spark installation is completely ignored. This approach minimizes the chance of dependency version conflicts. </div> </div> <div class="sect2"> <h3 id="_prerequisites">Prerequisites</h3> <div class="paragraph"> This recipe is suitable for both a real external and a local pseudo Hadoop cluster. While the recipe is maintained for the vanilla Hadoop pseudo-cluster, it has been reported to work on real clusters with Hadoop distributions from various vendors. </div> <div class="paragraph"> If you want to try the recipe on a local Hadoop pseudo-cluster, the easiest way to install it is to look at the install script at <a href="https://github.com/apache/tinkerpop/blob/3.7.3/docker/hadoop/install.sh">install.sh</a> and the <code>start hadoop</code> section of <a href="https://github.com/apache/tinkerpop/blob/3.7.3/docker/scripts/build.sh">build.sh</a>. </div> <div class="paragraph"> This recipe assumes that you installed the Gremlin Console with the <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#spark-plugin">Spark plugin</a> (the <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#hadoop-plugin">Hadoop plugin</a> is optional). Your Hadoop cluster may have been configured to use file compression, e.g. LZO compression. If so, you need to copy the relevant jar (e.g. <code>hadoop-lzo-*.jar</code>) to Gremlin Console’s <code>ext/spark-gremlin/lib</code> folder. </div> <div class="paragraph"> For starting the Gremlin Console in the right environment, create a shell script (e.g. <code>bin/spark-yarn.sh</code>) with the contents below. Of course, actual values for <code>GREMLIN_HOME</code>, <code>HADOOP_HOME</code> and <code>HADOOP_CONF_DIR</code> need to be adapted to your particular environment. </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code>#!/bin/bash # Variables to be adapted to the actual environment GREMLIN_HOME=/home/yourdir/lib/apache-tinkerpop-gremlin-console-3.7.3-standalone export HADOOP_HOME=/usr/local/lib/hadoop-3.3.1 export HADOOP_CONF_DIR=/usr/local/lib/hadoop-3.3.1/etc/hadoop # Have TinkerPop find the hadoop cluster configs and hadoop native libraries export CLASSPATH=$HADOOP_CONF_DIR export JAVA_OPTIONS="-Djava.library.path=$HADOOP_HOME/lib/native:$HADOOP_HOME/lib/native/Linux-amd64-64" # Start gremlin-console without getting the HADOOP_GREMLIN_LIBS warning cd $GREMLIN_HOME [ ! -e empty ] && mkdir empty export HADOOP_GREMLIN_LIBS=$GREMLIN_HOME/empty bin/gremlin.sh</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_running_the_job">Running the job</h3> <div class="paragraph"> You can now run a gremlin OLAP query with Spark on YARN: </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code>$ hdfs dfs -put data/tinkerpop-modern.kryo . $ . bin/spark-yarn.sh</code></pre> </div> </div> <section class="tabs tabs-2"> <input id="tab-1729796894-1" type="radio" name="radio-set-1729796894-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796894-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796894-2" type="radio" name="radio-set-1729796894-1" class="tab-selector-2" /> <label for="tab-1729796894-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> hadoop = System.getenv('HADOOP_HOME') ==>/home/ubuntu/.sdkman/candidates/hadoop/current gremlin> hadoopConfDir = System.getenv('HADOOP_CONF_DIR') ==>null gremlin> archive = 'spark-gremlin.zip' ==>spark-gremlin.zip gremlin> archivePath = "/tmp/$archive" ==>/tmp/spark-gremlin.zip gremlin> ['bash', '-c', "rm -f $archivePath; cd ext/spark-gremlin/lib && zip $archivePath *.jar"].execute().waitFor() ==>0 gremlin> conf = new Configurations().properties(new File('conf/hadoop/hadoop-gryo.properties')) ==>org.apache.commons.configuration2.PropertiesConfiguration@6d87253e gremlin> conf.setProperty('spark.master', 'yarn') ==>null gremlin> conf.setProperty('spark.submit.deployMode', 'client') ==>null gremlin> conf.setProperty('spark.yarn.archive', "$archivePath") ==>null gremlin> conf.setProperty('spark.yarn.appMasterEnv.CLASSPATH', "./__spark_libs__/*:$hadoopConfDir") ==>null gremlin> conf.setProperty('spark.executor.extraClassPath', "./__spark_libs__/*:$hadoopConfDir") ==>null gremlin> conf.setProperty('spark.driver.extraLibraryPath', "$hadoop/lib/native:$hadoop/lib/native/Linux-amd64-64") ==>null gremlin> conf.setProperty('spark.executor.extraLibraryPath', "$hadoop/lib/native:$hadoop/lib/native/Linux-amd64-64") ==>null gremlin> conf.setProperty('gremlin.spark.persistContext', 'true') ==>null gremlin> hdfs.copyFromLocal('data/tinkerpop-modern.kryo', 'tinkerpop-modern.kryo') ==>null gremlin> graph = GraphFactory.open(conf) ==>hadoopgraph[gryoinputformat->gryooutputformat] gremlin> g = traversal().withEmbedded(graph).withComputer(SparkGraphComputer) ==>graphtraversalsource[hadoopgraph[gryoinputformat->gryooutputformat], sparkgraphcomputer] gremlin> g.V().group().by(values('name')).by(both().count()) ==>[ripple:1,peter:1,vadas:1,josh:3,lop:3,marko:3]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">hadoop = System.getenv('HADOOP_HOME') hadoopConfDir = System.getenv('HADOOP_CONF_DIR') archive = 'spark-gremlin.zip' archivePath = "/tmp/$archive" ['bash', '-c', "rm -f $archivePath; cd ext/spark-gremlin/lib && zip $archivePath *.jar"].execute().waitFor() conf = new Configurations().properties(new File('conf/hadoop/hadoop-gryo.properties')) conf.setProperty('spark.master', 'yarn') conf.setProperty('spark.submit.deployMode', 'client') conf.setProperty('spark.yarn.archive', "$archivePath") conf.setProperty('spark.yarn.appMasterEnv.CLASSPATH', "./__spark_libs__/*:$hadoopConfDir") conf.setProperty('spark.executor.extraClassPath', "./__spark_libs__/*:$hadoopConfDir") conf.setProperty('spark.driver.extraLibraryPath', "$hadoop/lib/native:$hadoop/lib/native/Linux-amd64-64") conf.setProperty('spark.executor.extraLibraryPath', "$hadoop/lib/native:$hadoop/lib/native/Linux-amd64-64") conf.setProperty('gremlin.spark.persistContext', 'true') hdfs.copyFromLocal('data/tinkerpop-modern.kryo', 'tinkerpop-modern.kryo') graph = GraphFactory.open(conf) g = traversal().withEmbedded(graph).withComputer(SparkGraphComputer) g.V().group().by(values('name')).by(both().count())</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> If you run into exceptions, you will have to dig into the logs. You can do this from the command line with <code>yarn application -list -appStates ALL</code> to find the <code>applicationId</code>, while the logs are available with <code>yarn logs -applicationId application_1498627870374_0008</code>. Alternatively, you can inspect the logs via the YARN Resource Manager UI (e.g. http://rm.your.domain:8088/cluster), provided that YARN was configured with the <code>yarn.log-aggregation-enable</code> property set to <code>true</code>. See the Spark documentation for <a href="https://spark.apache.org/docs/latest/running-on-yarn.html#debugging-your-application">additional hints</a>. </div> </div> <div class="sect2"> <h3 id="_explanation">Explanation</h3> <div class="paragraph"> This recipe does not require running the <code>bin/hadoop/init-tp-spark.sh</code> script described in the <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#sparkgraphcomputer">reference documentation</a> and thus is also valid for cluster users without access permissions to do so. </div> <div class="paragraph"> Rather, it exploits the <code>spark.yarn.archive</code> property, which points to an archive with jars on the local file system and is loaded into the various YARN containers. As a result the <code>spark-gremlin.zip</code> archive becomes available as the directory named <code>__spark_libs__</code> in the YARN containers. The <code>spark.executor.extraClassPath</code> and <code>spark.yarn.appMasterEnv.CLASSPATH</code> properties point to the jars inside this directory. This is why they contain the <code>./__spark_lib__/*</code> item. Just because a Spark executor got the archive with jars loaded into its container, does not mean it knows how to access them. </div> <div class="paragraph"> Also the <code>HADOOP_GREMLIN_LIBS</code> mechanism is not used because it can not work for Spark on YARN as implemented (jars added to the <code>SparkContext</code> are not available to the YARN application master). </div> <div class="paragraph"> The <code>gremlin.spark.persistContext</code> property is explained in the reference documentation of <a href="https://tinkerpop.apache.org/docs/3.7.3/reference/#sparkgraphcomputer">SparkGraphComputer</a>: it helps in getting follow-up OLAP queries answered faster, because you skip the overhead for getting resources from YARN. </div> </div> <div class="sect2"> <h3 id="_additional_configuration_options">Additional configuration options</h3> <div class="paragraph"> This recipe does most of the graph configuration in the Gremlin Console so that environment variables can be used and the chance of configuration mistakes is minimal. Once you have your setup working, it is probably easier to make a copy of the <code>conf/hadoop/hadoop-gryo.properties</code> file and put the property values specific to your environment there. This is also the right moment to take a look at the <code>spark-defaults.xml</code> file of your cluster, in particular the settings for the <a href="https://spark.apache.org/docs/latest/monitoring.html">Spark History Service</a>, which allows you to access logs of finished applications via the YARN resource manager UI. </div> <div class="paragraph"> This recipe uses the Gremlin Console, but things should not be very different for your own JVM-based application, as long as you do not use the <code>spark-submit</code> or <code>spark-shell</code> commands. You will also want to check the additional runtime dependencies listed in the <code>Gremlin-Plugin-Dependencies</code> section of the manifest file in the <code>spark-gremlin</code> jar. </div> <div class="paragraph"> You may not like the idea that the Hadoop and Spark jars from the TinkerPop distribution differ from the versions in your cluster. If so, just build TinkerPop from source with the corresponding dependencies changed in the various <code>pom.xml</code> files (e.g. <code>spark-core_2.11-2.2.0-some-vendor.jar</code> instead of <code>spark-core_2.11-2.2.0.jar</code>). Of course, TinkerPop will only build for exactly matching or slightly differing artifact versions. </div> </div> </div> </div> <h1 id="_anti_patterns" class="sect0">Anti-Patterns</h1> <div class="openblock partintro"> <div class="content"> <img src="../images/gremlin-anti-gremlin.png" alt="gremlin anti gremlin" width="250"> </div> </div> <div class="sect1"> <h2 id="long-traversals">Long Traversals</h2> <div class="sectionbody"> <div class="paragraph"> It can be tempting to generate long traversals, e.g. to create a set of vertices and edges based on information that resides within an application. For example, let’s consider two lists - one that contains information about persons and another that contains information about the relationship between these persons. To illustrate the problem we will create two list with a few random map entries. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-1" type="radio" name="radio-set-1729796922-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-2" type="radio" name="radio-set-1729796922-1" class="tab-selector-2" /> <label for="tab-1729796922-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> :set max-iteration 10 gremlin> rnd = new Random(123) ; x = [] gremlin> persons = (1..100).collect {["id": it, "name": "person ${it}", "age": rnd.nextInt(40) + 20]} ==>[id:1,name:person 1,age:42] ==>[id:2,name:person 2,age:30] ==>[id:3,name:person 3,age:36] ==>[id:4,name:person 4,age:49] ==>[id:5,name:person 5,age:55] ==>[id:6,name:person 6,age:37] ==>[id:7,name:person 7,age:54] ==>[id:8,name:person 8,age:57] ==>[id:9,name:person 9,age:45] ==>[id:10,name:person 10,age:33] ... gremlin> relations = (1..500).collect {[rnd.nextInt(persons.size()), rnd.nextInt(persons.size())]}. unique().grep {it[0] != it[1] && !x.contains(it.reverse())}.collect { x << it minAge = Math.min(persons[it[0]].age, persons[it[1]].age) knowsSince = new Date().year + 1900 - rnd.nextInt(minAge) ["from": persons[it[0]].id, "to": persons[it[1]].id, "since": knowsSince] } ==>[from:21,to:11,since:2020] ==>[from:59,to:61,since:2018] ==>[from:1,to:37,since:2016] ==>[from:83,to:45,since:2012] ==>[from:21,to:51,since:2020] ==>[from:27,to:5,since:2017] ==>[from:77,to:89,since:2021] ==>[from:16,to:44,since:2016] ==>[from:95,to:53,since:1977] ==>[from:20,to:22,since:2022] ... gremlin> [ "Number of persons": persons.size() , "Number of unique relationships": relations.size() ] ==>Number of persons=100 ==>Number of unique relationships=478</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">:set max-iteration 10 rnd = new Random(123) ; x = [] persons = (1..100).collect {["id": it, "name": "person ${it}", "age": rnd.nextInt(40) + 20]} relations = (1..500).collect {[rnd.nextInt(persons.size()), rnd.nextInt(persons.size())]}. unique().grep {it[0] != it[1] && !x.contains(it.reverse())}.collect { x << it minAge = Math.min(persons[it[0]].age, persons[it[1]].age) knowsSince = new Date().year + 1900 - rnd.nextInt(minAge) ["from": persons[it[0]].id, "to": persons[it[1]].id, "since": knowsSince] } [ "Number of persons": persons.size() , "Number of unique relationships": relations.size() ]</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Now, to create the <code>person</code> vertices and the <code>knows</code> edges between them it may look like a good idea to generate a single graph-mutating traversal, just like this: </div> <section class="tabs tabs-2"> <input id="tab-1729796922-3" type="radio" name="radio-set-1729796922-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-4" type="radio" name="radio-set-1729796922-3" class="tab-selector-2" /> <label for="tab-1729796922-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> t = g ==>graphtraversalsource[tinkergraph[vertices:0 edges:0], standard] gremlin> for (person in persons) { t = t.addV("person"). property(id, person.id). property("name", person.name). property("age", person.age).as("p${person.id}") } ; [] gremlin> for (relation in relations) { t = t.addE("knows").property("since", relation.since). from("p${relation.from}"). to("p${relation.to}") } ; [] gremlin> traversalAsString = org.apache.tinkerpop.gremlin.process.traversal.translator.GroovyTranslator.of("g").translate(t.bytecode).getScript() ; [] gremlin> [ "Traversal String Length": traversalAsString.length() , "Traversal Preview": traversalAsString.replaceFirst(/^(.{104}).*(.{64})$/, '$1 ... $2') ] ==>Traversal String Length=41086 ==>Traversal Preview=g.addV("person").property(T.id,(int) 1).property("name",person 1).property("age",(int) 42).as("p1").addV ... addE("knows").property("since",(int) 2010).from("p47").to("p48")</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">t = g for (person in persons) { t = t.addV("person"). property(id, person.id). property("name", person.name). property("age", person.age).as("p${person.id}") } ; [] for (relation in relations) { t = t.addE("knows").property("since", relation.since). from("p${relation.from}"). to("p${relation.to}") } ; [] traversalAsString = org.apache.tinkerpop.gremlin.process.traversal.translator.GroovyTranslator.of("g").translate(t.bytecode).getScript() ; [] [ "Traversal String Length": traversalAsString.length() , "Traversal Preview": traversalAsString.replaceFirst(/^(.{104}).*(.{64})$/, '$1 ... $2') ]</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> However, this kind of traversal does not scale and it’s prone to produce a <code>StackOverflowError</code>. This error can hardly be prevented as it’s a limit imposed by the JVM. The stack size can be increased using the <code>-Xss</code> JVM option, but that’s not how the problem that’s discussed here, should be solved. The proper way to accomplish the same thing as in the traversal above is to inject the lists into the traversal and process them from there. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-5" type="radio" name="radio-set-1729796922-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-6" type="radio" name="radio-set-1729796922-5" class="tab-selector-2" /> <label for="tab-1729796922-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSideEffect("rels", relations). inject(persons).sideEffect( unfold(). addV("person"). property(id, select("id")). property("name", select("name")). property("age", select("age")). group("m"). by(id). by(unfold())). select("rels").unfold().as("r"). addE("knows"). from(select("m").select(select("r").select("from"))). to(select("m").select(select("r").select("to"))). property("since", select("since")).iterate() gremlin> g ==>graphtraversalsource[tinkergraph[vertices:100 edges:478], standard]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSideEffect("rels", relations). inject(persons).sideEffect( unfold(). addV("person"). property(id, select("id")). property("name", select("name")). property("age", select("age")). group("m"). by(id). by(unfold())). select("rels").unfold().as("r"). addE("knows"). from(select("m").select(select("r").select("from"))). to(select("m").select(select("r").select("to"))). property("since", select("since")).iterate() g</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Obviously, these traversals are more complicated, but the number of steps is known and thus it’s the best way to prevent an unexpected <code>StackOverflowError</code>. Furthermore, shorter traversals reduce the (de)serialization costs when such a traversal is send over the wire to a Gremlin Server. </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> Although the example was based on a graph-mutating traversal, the same rules apply for read-only and mixed traversals. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="unspecified-keys-and-labels">Unspecified Keys and Labels</h2> <div class="sectionbody"> <div class="paragraph"> Some Gremlin steps have optional arguments that represent keys (e.g. <code>elementMap()</code>, valueMap()<code>) or labels (e.g. `out()</code>). In the prototyping phase of a projects it’s often convenient to use these steps without any arguments. However, in production code this is bad idea and keys and labels should always be specified. Not only does it make the traversal easier to read for others, but it also ensures that the application will not break if the schema changes at one point and the queries return completely different results. </div> <div class="paragraph"> The following code block shows a few examples that are good for prototyping or graph discovery. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-7" type="radio" name="radio-set-1729796922-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-8" type="radio" name="radio-set-1729796922-7" class="tab-selector-2" /> <label for="tab-1729796922-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("person","name","marko").out() ==>v[3] ==>v[2] ==>v[4] gremlin> g.V().has("person","name","marko").out("created").elementMap() ==>[id:3,label:software,name:lop,lang:java] gremlin> g.V().has("software","name","ripple").inE().has("weight", gte(0.5)).outV().properties() ==>vp[name->josh] ==>vp[age->32]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("person","name","marko").out() g.V().has("person","name","marko").out("created").elementMap() g.V().has("software","name","ripple").inE().has("weight", gte(0.5)).outV().properties()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The next code block shows the same queries, but with specified keys and labels. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-9" type="radio" name="radio-set-1729796922-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-10" type="radio" name="radio-set-1729796922-9" class="tab-selector-2" /> <label for="tab-1729796922-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has("person","name","marko").out("created","knows") ==>v[3] ==>v[2] ==>v[4] gremlin> g.V().has("person","name","marko").out("created").elementMap("name","lang") ==>[id:3,label:software,name:lop,lang:java] gremlin> g.V().has("software","name","ripple").inE("created").has("weight", gte(0.5)).outV(). properties("name","age") ==>vp[name->josh] ==>vp[age->32]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has("person","name","marko").out("created","knows") g.V().has("person","name","marko").out("created").elementMap("name","lang") g.V().has("software","name","ripple").inE("created").has("weight", gte(0.5)).outV(). properties("name","age")</code></pre> </div> </div> </div> </div> </section> </div> </div> <div class="sect1"> <h2 id="unnecessary-steps">Unnecessary Steps</h2> <div class="sectionbody"> <div class="paragraph"> There are quite a few steps and patterns that can be combined into a much shorter form. TinkerPop is trying to optimize queries, by rewriting such patterns automatically using traversal optimization strategies. These strategies, however, do have a few preconditions and under certain circumstance they will not attempt to rewrite a traversal. For example, if the traversal has path computations enabled (e.g. by using certain steps, such as <code>path()</code>, <code>simplePath()</code>, <code>otherV()</code>, etc.), then the assumption is that all steps are required in order to produce the desired path. </div> <div class="paragraph"> An often seen anti-pattern is the one that explicitly traverses to an edge and then to a vertex without using any filters. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-11" type="radio" name="radio-set-1729796922-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-12" type="radio" name="radio-set-1729796922-11" class="tab-selector-2" /> <label for="tab-1729796922-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel("person").outE("created").inV().dedup() //// (1) ==>v[3] ==>v[5] gremlin> g.V().hasLabel("software").inE("created").outV().count() //// (2) ==>4</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel("person").outE("created").inV().dedup() //// (1) g.V().hasLabel("software").inE("created").outV().count() //2</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> The <code>created</code> edge is never really needed as the traversal only asks for all things that were created by all persons in the graph. These "things" are only represented by the adjacent vertices, not the edges. </li> <li> This traversals counts the persons in the graph who created software. The interesting thing about this query is that it actually doesn’t need to traverse all the way to the <code>person</code> vertices to count them. In this case it’s sufficient to count the edges between the <code>software</code> and <code>person</code> vertices. The performance of this query pretty much depends on the particular provider implementation, but counting incident edges is usually much faster than counting adjacent vertices. </li> </ol> </div> <div class="paragraph"> The next code block shows the two aforementioned queries properly rewritten. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-13" type="radio" name="radio-set-1729796922-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-14" type="radio" name="radio-set-1729796922-13" class="tab-selector-2" /> <label for="tab-1729796922-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel("person").out("created").dedup() ==>v[3] ==>v[5] gremlin> g.V().hasLabel("software").inE("created").count() ==>4</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel("person").out("created").dedup() g.V().hasLabel("software").inE("created").count()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Another anti-pattern that is commonly seen is the chaining of <code>where()</code>-steps using predicates. Consider the following traversal: </div> <section class="tabs tabs-2"> <input id="tab-1729796922-15" type="radio" name="radio-set-1729796922-15" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-15" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-16" type="radio" name="radio-set-1729796922-15" class="tab-selector-2" /> <label for="tab-1729796922-16" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().as('a'). both().where(lt('a')).by(id).as('b'). both().where(lt('a')).by(id).where(gt('b')).by(id).as('c'). not(both().where(eq('a'))). select('a','b','c'). by('name') ==>[a:lop,b:marko,c:vadas] ==>[a:josh,b:marko,c:vadas] ==>[a:peter,b:lop,c:josh]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().as('a'). both().where(lt('a')).by(id).as('b'). both().where(lt('a')).by(id).where(gt('b')).by(id).as('c'). not(both().where(eq('a'))). select('a','b','c'). by('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Ignoring the anti-patterns that were discussed before, there’s not much wrong with the traversal, but note the two chained <code>where()</code>-steps (<code>where(lt('a')).by(id).where(gt('b'))).by(id)</code>). Both steps compare the id of the current vertex with the id of a previous vertex. These two conditions can be combined on the predicate level. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-17" type="radio" name="radio-set-1729796922-17" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-17" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-18" type="radio" name="radio-set-1729796922-17" class="tab-selector-2" /> <label for="tab-1729796922-18" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().as('a'). both().where(lt('a')).by(id).as('b'). both().where(lt('a').and(gt('b'))).by(id).as('c'). not(both().where(eq('a'))). select('a','b','c'). by('name') ==>[a:lop,b:marko,c:vadas] ==>[a:josh,b:marko,c:vadas] ==>[a:peter,b:lop,c:josh]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().as('a'). both().where(lt('a')).by(id).as('b'). both().where(lt('a').and(gt('b'))).by(id).as('c'). not(both().where(eq('a'))). select('a','b','c'). by('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The <code>profile()</code> output of both queries should make clear why this is better than using two <code>where()</code>-steps. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-19" type="radio" name="radio-set-1729796922-19" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-19" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-20" type="radio" name="radio-set-1729796922-19" class="tab-selector-2" /> <label for="tab-1729796922-20" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().as('a'). both().where(lt('a')).by(id).as('b'). both().where(lt('a')).by(id).where(gt('b')).by(id).as('c'). not(both().where(eq('a'))). select('a','b','c'). by('name'). profile() ==>Traversal Metrics Step Count Traversers Time (ms) % Dur ============================================================================================================= TinkerGraphStep(vertex,[])@[a] 6 6 0.156 10.45 VertexStep(BOTH,vertex) 12 12 0.094 6.32 WherePredicateStep(null,lt(a),[id])@[b] 6 6 0.215 14.34 NoOpBarrierStep(2500) 6 6 0.039 2.66 VertexStep(BOTH,vertex) 18 18 0.137 9.20 NotStep([VertexStep(BOTH,vertex), WherePredicat... 15 15 0.421 28.13 VertexStep(BOTH,vertex) 40 40 0.130 WherePredicateStep(null,eq(a)) 0.163 WherePredicateStep(null,lt(a),[id]) 6 6 0.191 12.76 NoOpBarrierStep(2500) 6 6 0.032 2.17 WherePredicateStep(null,gt(b),[id])@[c] 3 3 0.071 4.76 NoOpBarrierStep(2500) 3 3 0.024 1.66 SelectStep(last,[a, b, c],[value(name)]) 3 3 0.058 3.93 NoOpBarrierStep(2500) 3 3 0.054 3.63 >TOTAL - - 1.499 - gremlin> g.V().as('a'). both().where(lt('a')).by(id).as('b'). both().where(lt('a').and(gt('b'))).by(id).as('c'). not(both().where(eq('a'))). select('a','b','c'). by('name'). profile() ==>Traversal Metrics Step Count Traversers Time (ms) % Dur ============================================================================================================= TinkerGraphStep(vertex,[])@[a] 6 6 0.124 10.49 VertexStep(BOTH,vertex) 12 12 0.086 7.26 WherePredicateStep(null,lt(a),[id])@[b] 6 6 0.153 12.87 NoOpBarrierStep(2500) 6 6 0.067 5.66 VertexStep(BOTH,vertex) 18 18 0.047 4.03 NotStep([VertexStep(BOTH,vertex), WherePredicat... 15 15 0.344 28.97 VertexStep(BOTH,vertex) 40 40 0.094 WherePredicateStep(null,eq(a)) 0.147 WherePredicateStep(null,and(lt(a), gt(b)),[id])... 3 3 0.212 17.85 NoOpBarrierStep(2500) 3 3 0.043 3.67 SelectStep(last,[a, b, c],[value(name)]) 3 3 0.053 4.51 NoOpBarrierStep(2500) 3 3 0.055 4.68 >TOTAL - - 1.190 -</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().as('a'). both().where(lt('a')).by(id).as('b'). both().where(lt('a')).by(id).where(gt('b')).by(id).as('c'). not(both().where(eq('a'))). select('a','b','c'). by('name'). profile() g.V().as('a'). both().where(lt('a')).by(id).as('b'). both().where(lt('a').and(gt('b'))).by(id).as('c'). not(both().where(eq('a'))). select('a','b','c'). by('name'). profile()</code></pre> </div> </div> </div> </div> </section> </div> </div> <div class="sect1"> <h2 id="unspecified-label-in-global-vertex-lookup">Unspecified Label in Global Vertex lookup</h2> <div class="sectionbody"> <div class="paragraph"> The severity of the anti-pattern described in this section heavily depends on the provider implementation. Throughout the TinkerPop documentation the code samples often use traversals that start like this: </div> <section class="tabs tabs-2"> <input id="tab-1729796922-21" type="radio" name="radio-set-1729796922-21" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-21" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-22" type="radio" name="radio-set-1729796922-21" class="tab-selector-2" /> <label for="tab-1729796922-22" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko') ==>v[1]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> This is totally fine for TinkerGraph as it uses a very simplified indexing schema, e.g. every vertex that has a certain property is stored in the same index. However, providers may prefer to use separate indexes for different vertex labels. This becomes more important as graphs grow much larger over time (which is not what TinkerGraph is meant to do). Hence, any traversal that’s going to be used in production code should also specify the vertex label to prevent the query engine from searching every index for the provided property value. </div> <div class="paragraph"> The easy fix for the initially mentioned query follows in the code block below. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-23" type="radio" name="radio-set-1729796922-23" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-23" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-24" type="radio" name="radio-set-1729796922-23" class="tab-selector-2" /> <label for="tab-1729796922-24" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel('person').has('name','marko') //// (1) ==>v[1] gremlin> g.V().has('person','name','marko') //// (2) ==>v[1]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel('person').has('name','marko') //// (1) g.V().has('person','name','marko') //2</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> With the specified label the traversal still returns the same result, but it’s much safer to use across different providers. </li> <li> Same as statement 1, but a much shorter form to improve readability. </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="steps-instead-of-tokens">Steps Instead of Tokens</h2> <div class="sectionbody"> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> As of 3.5.0, <code>ByModulatorOptimizationStrategy</code> is present to automatically translate this anti-pattern to their more performant versions for most cases however, it is still best to write Gremlin according to the contents that follow. </td> </tr> </table> </div> <div class="paragraph"> When child traversals contain a single step, there’s a good chance that the step can be replaced with a token. These tokens are translated into optimized traversals that execute much faster then their step traversal pendants. A few examples of single step child traversals are shown in the following code block. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-25" type="radio" name="radio-set-1729796922-25" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-25" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-26" type="radio" name="radio-set-1729796922-25" class="tab-selector-2" /> <label for="tab-1729796922-26" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().groupCount().by(label()) ==>[software:2,person:4] gremlin> g.V().group().by(label()).by(id().fold()) ==>[software:[3,5],person:[1,2,4,6]] gremlin> g.V().project("id","label"). by(id()). by(label()) ==>[id:1,label:person] ==>[id:2,label:person] ==>[id:3,label:software] ==>[id:4,label:person] ==>[id:5,label:software] ==>[id:6,label:person] gremlin> g.V().choose(label()). option("person", project("person").by(values("name"))). option("software", project("product").by(values("name"))) ==>[person:marko] ==>[person:vadas] ==>[product:lop] ==>[person:josh] ==>[product:ripple] ==>[person:peter]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().groupCount().by(label()) g.V().group().by(label()).by(id().fold()) g.V().project("id","label"). by(id()). by(label()) g.V().choose(label()). option("person", project("person").by(values("name"))). option("software", project("product").by(values("name")))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> With tokens used instead of steps the traversals become a little shorter and more readable. </div> <section class="tabs tabs-2"> <input id="tab-1729796922-27" type="radio" name="radio-set-1729796922-27" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-27" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-28" type="radio" name="radio-set-1729796922-27" class="tab-selector-2" /> <label for="tab-1729796922-28" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().groupCount().by(label) ==>[software:2,person:4] gremlin> g.V().group().by(label).by(id) //// (1) ==>[software:[3,5],person:[1,2,4,6]] gremlin> g.V().project("id","label"). by(id). by(label) ==>[id:1,label:person] ==>[id:2,label:person] ==>[id:3,label:software] ==>[id:4,label:person] ==>[id:5,label:software] ==>[id:6,label:person] gremlin> g.V().choose(label). option("person", project("person").by("name")). option("software", project("product").by("name")) //// (2) ==>[person:marko] ==>[person:vadas] ==>[product:lop] ==>[person:josh] ==>[product:ripple] ==>[person:peter]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().groupCount().by(label) g.V().group().by(label).by(id) //// (1) g.V().project("id","label"). by(id). by(label) g.V().choose(label). option("person", project("person").by("name")). option("software", project("product").by("name")) //2</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> Note, that tokens use a <code>fold()</code> reducer by default. </li> <li> <code>by("name")</code> doesn’t use a token, but falls into the same category as the String <code>"name"</code> is translated into an optimized traversal. </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_has_and_traversal_arguments">has() and Traversal Arguments</h2> <div class="sectionbody"> <div class="paragraph"> There is an understandable assumption that the <code>has(String,Traversal)</code> overload indicates that the value returned by the <code>Traversal</code> argument will be used as the comparative value for the specified property key. There are often similar assumptions that values of <code>P</code> can take a <code>Traversal</code> argument to achieve a similar end as in <code>has(String, eq(Traversal))</code>. Unfortunately, neither of these work as assumed. </div> <div class="paragraph"> Starting with the latter issue of <code>P</code> and <code>Traversal</code> it should be noted that while <code>P</code> values take <code>Object</code> and thus a <code>Traversal</code> it does not mean the <code>Traversal</code> will be resolved to a result that will be comparable. <code>P</code> will rather do a compare on the raw <code>Traversal</code> object which of course will always return <code>false</code> (unless for some odd reason you happen to store that <code>Traversal</code> object in your graph): </div> <section class="tabs tabs-2"> <input id="tab-1729796922-29" type="radio" name="radio-set-1729796922-29" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-29" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-30" type="radio" name="radio-set-1729796922-29" class="tab-selector-2" /> <label for="tab-1729796922-30" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name', eq(constant('josh'))) gremlin> eq(constant('josh')) ==>eq([ConstantStep(josh)])</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name', eq(constant('josh'))) eq(constant('josh'))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> As for the former issue with <code>has(String,Traversal)</code>, this requires a bit more explanation. The <code>Traversal</code> object is meant to be treated as a <code>Predicate</code>, meaning that if it returns a value the <code>has()</code> will allow the traverser to pass: </div> <section class="tabs tabs-2"> <input id="tab-1729796922-31" type="radio" name="radio-set-1729796922-31" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-31" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-32" type="radio" name="radio-set-1729796922-31" class="tab-selector-2" /> <label for="tab-1729796922-32" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name', constant('josh')) //// (1) ==>v[1] ==>v[2] ==>v[3] ==>v[4] ==>v[5] ==>v[6] gremlin> g.V().has('name', constant('josh').is('xyz')) //// (2)</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name', constant('josh')) //// (1) g.V().has('name', constant('josh').is('xyz')) //2</code></pre> </div> </div> </div> </div> </section> <div class="colist arabic"> <ol> <li> <code>constant()</code> always returns a value so all vertices pass through the <code>has()</code> </li> <li> By adding <code>is()</code> this <code>Traversal</code> will no longer return a value so no vertices pass through the <code>has()</code> </li> </ol> </div> <div class="paragraph"> These examples are a bit contrived for sake of demonstration, but the common pattern folks attempt appears as follows: </div> <section class="tabs tabs-2"> <input id="tab-1729796922-33" type="radio" name="radio-set-1729796922-33" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-33" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-34" type="radio" name="radio-set-1729796922-33" class="tab-selector-2" /> <label for="tab-1729796922-34" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSideEffect('x',['name': 'josh']).V().has('name', select('x').select('name')) ==>v[1] ==>v[2] ==>v[3] ==>v[4] ==>v[5] ==>v[6]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSideEffect('x',['name': 'josh']).V().has('name', select('x').select('name'))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The above example represents a commonly seen mistake where we try to dynamically inject the value "josh" from a <code>Map</code> stored in a side-effect named "x". As we can see, since <code>select('x').select('name')</code> returns a value the <code>has()</code> succeeds for every single vertex which is unexpected. The correct way to do this dynamic injection is with <code>where()</code> as in the following example: </div> <section class="tabs tabs-2"> <input id="tab-1729796922-35" type="radio" name="radio-set-1729796922-35" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-35" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-36" type="radio" name="radio-set-1729796922-35" class="tab-selector-2" /> <label for="tab-1729796922-36" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.withSideEffect('x',['name': 'josh']).V().as('a').where('a',eq('x')).by('name') ==>v[4]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.withSideEffect('x',['name': 'josh']).V().as('a').where('a',eq('x')).by('name')</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> As a final note on this topic, it’s worth noting how <code>has(String,Traversal)</code> can be used. Note that the traverser that starts the <code>Traversal</code> argument is the <code>Property</code> value being compared. Therefore, if we wanted to find all the vertices that had the "name" of "josh" we would do: </div> <section class="tabs tabs-2"> <input id="tab-1729796922-37" type="radio" name="radio-set-1729796922-37" class="tab-selector-1" checked="checked" /> <label for="tab-1729796922-37" class="tab-label-1">console (groovy)</label> <input id="tab-1729796922-38" type="radio" name="radio-set-1729796922-37" class="tab-selector-2" /> <label for="tab-1729796922-38" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name', is('josh')) ==>v[4]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name', is('josh'))</code></pre> </div> </div> </div> </div> </section> </div> </div> <h1 id="_implementation_recipes" class="sect0">Implementation Recipes</h1> <div class="sect1"> <h2 id="style-guide">Style Guide</h2> <div class="sectionbody"> <div class="paragraph"> The Gremlin Style Guide has been moved and expanded as part of <a href="https://gremlint.com">Gremlint</a>. Please find that style guide <a href="https://tinkerpop.apache.org/gremlint/#/style-guide">here</a>. </div> </div> </div> <div class="sect1"> <h2 id="traversal-component-reuse">Traversal Component Reuse</h2> <div class="sectionbody"> <div class="paragraph"> Good software development practices require reuse to keep software maintainable. In Gremlin, there are often bits of traversal logic that could be represented as components that might be tested independently and utilized as part of other traversals. One approach to doing this would be to extract such logic into an anonymous traversal and provide it to a parent traversal through <code>flatMap()</code>-step. </div> <div class="paragraph"> Using the modern toy graph as an example, assume that there are number of traversals that are interested in filtering on edges where the "weight" property is greater than "0.5". A query like that might look like this: </div> <section class="tabs tabs-2"> <input id="tab-1729796938-1" type="radio" name="radio-set-1729796938-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796938-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796938-2" type="radio" name="radio-set-1729796938-1" class="tab-selector-2" /> <label for="tab-1729796938-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(1).outE("knows").has('weight', P.gt(0.5d)).inV().both() ==>v[5] ==>v[3] ==>v[1]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(1).outE("knows").has('weight', P.gt(0.5d)).inV().both()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Repeatedly requiring that filter on "weight" could lead to a lot of duplicate code, which becomes difficult to maintain. It would be nice to extract that logic so as to centralize it for reuse in all places where needed. An anonymous traversal allows that to happen and can be created as follows. </div> <section class="tabs tabs-2"> <input id="tab-1729796938-3" type="radio" name="radio-set-1729796938-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796938-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796938-4" type="radio" name="radio-set-1729796938-3" class="tab-selector-2" /> <label for="tab-1729796938-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> weightFilter = outE("knows").has('weight', P.gt(0.5d)).inV();[] gremlin> g.V(1).flatMap(weightFilter).both() ==>v[5] ==>v[3] ==>v[1]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">weightFilter = outE("knows").has('weight', P.gt(0.5d)).inV();[] g.V(1).flatMap(weightFilter).both()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The <code>weightFilter</code> is an anonymous traversal and it is created by way <code>__</code> class. The <code>__</code> is omitted above from initalization of <code>weightFilter</code> because it is statically imported to the Gremlin Console. The <code>weightFilter</code> gets passed to the "full" traversal by way for <code>flatMap()</code>-step and the results are the same. Of course, there is a problem. If there is an attempt to use that <code>weightFilter</code> a second time, the traversal with thrown an exception because both the <code>weightFilter</code> and parent traversal have been "compiled" which prevents their re-use. A simple fix to this would be to clone the <code>weightFilter</code>. </div> <section class="tabs tabs-2"> <input id="tab-1729796938-5" type="radio" name="radio-set-1729796938-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796938-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796938-6" type="radio" name="radio-set-1729796938-5" class="tab-selector-2" /> <label for="tab-1729796938-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> weightFilter = outE("knows").has('weight', P.gt(0.5d)).inV();[] gremlin> g.V(1).flatMap(weightFilter.clone()).both() ==>v[5] ==>v[3] ==>v[1] gremlin> g.V(1).flatMap(weightFilter.clone()).bothE().otherV() ==>v[5] ==>v[3] ==>v[1] gremlin> g.V(1).flatMap(weightFilter.clone()).groupCount() ==>[v[4]:1]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">weightFilter = outE("knows").has('weight', P.gt(0.5d)).inV();[] g.V(1).flatMap(weightFilter.clone()).both() g.V(1).flatMap(weightFilter.clone()).bothE().otherV() g.V(1).flatMap(weightFilter.clone()).groupCount()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Now the <code>weightFilter</code> can be reused over and over again. Remembering to <code>clone()</code> might lead to yet another maintenance issue in that failing to recall that step would likely result in a bug. One option might be to wrap the <code>weightFilter</code> creation in a function that returns the clone. Another approach might be to parameterize that function to construct a new anonymous traversal each time with the idea being that this might gain even more flexibility in parameterizing the anonymous traversal itself. </div> <section class="tabs tabs-2"> <input id="tab-1729796938-7" type="radio" name="radio-set-1729796938-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796938-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796938-8" type="radio" name="radio-set-1729796938-7" class="tab-selector-2" /> <label for="tab-1729796938-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> weightFilter = { w -> outE("knows").has('weight', P.gt(w)).inV() } ==>groovysh_evaluate$_run_closure1@b75f3f4 gremlin> g.V(1).flatMap(weightFilter(0.5d)).both() ==>v[5] ==>v[3] ==>v[1] gremlin> g.V(1).flatMap(weightFilter(0.5d)).bothE().otherV() ==>v[5] ==>v[3] ==>v[1] gremlin> g.V(1).flatMap(weightFilter(0.5d)).groupCount() ==>[v[4]:1]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">weightFilter = { w -> outE("knows").has('weight', P.gt(w)).inV() } g.V(1).flatMap(weightFilter(0.5d)).both() g.V(1).flatMap(weightFilter(0.5d)).bothE().otherV() g.V(1).flatMap(weightFilter(0.5d)).groupCount()</code></pre> </div> </div> </div> </div> </section> </div> </div> <h1 id="contributing" class="sect0">How to Contribute a Recipe</h1> <div class="openblock partintro"> <div class="content"> <div class="paragraph"> Recipes are generated under the same system as all TinkerPop documentation and is stored directly in the source code repository. TinkerPop documentation is all <a href="http://asciidoc.org/">asciidoc</a> based and can be generated locally with either <a href="https://tinkerpop.apache.org/docs/3.7.3/dev/developer/#building-testing">shell script/Maven</a> or <a href="https://tinkerpop.apache.org/docs/3.7.3/dev/developer/#docker-integration">Docker</a> build commands. Once changes are complete, submit a pull request for review by TinkerPop committers. </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> Please review existing recipes and attempt to conform to their writing and visual style. It may also be a good idea to discuss ideas for a recipe on the <a href="https://lists.apache.org/list.html?dev@tinkerpop.apache.org">developer mailing list</a> prior to starting work on it, as the community might provide insight on the approach and idea that would be helpful. It is preferable that a <a href="https://issues.apache.org/jira/browse/TINKERPOP">JIRA issue</a> be opened that describes the nature of the recipe so that the eventual pull request can be bound to that issue. </td> </tr> </table> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <div class="title">Important</div> </td> <td class="content"> Please read TinkerPop’s <a href="https://tinkerpop.apache.org/docs/3.7.3/dev/developer/#_contributing">policy on contributing</a> prior to submitting a recipe. </td> </tr> </table> </div> <div class="paragraph"> To contribute a recipe, first clone the repository: </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="shell">git clone https://github.com/apache/tinkerpop.git</code></pre> </div> </div> <div class="paragraph"> The recipes can be found in this directory: </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="shell">ls docs/src/recipes</code></pre> </div> </div> <div class="paragraph"> Each recipe exists within a separate <code>.asciidoc</code> file. The file name should match the name of the recipe. Recipe names should be short, but descriptive (as they need to fit in the left-hand table of contents when generated). The <code>index.asciidoc</code> is the parent document that "includes" the content of each individual recipe file. A recipe file is included in the <code>index.asciidoc</code> with an entry like this: <code>include::my-recipe.asciidoc[]</code> </div> <div class="paragraph"> Documentation should be generated locally for review prior to submitting a pull request. TinkerPop documentation is "live" in that it is bound to a specific version when generated. Furthermore, code examples (those that are <code>gremlin-groovy</code> based) are executed at document generation time with the results written directly into the output. The following command will generate the documentation with: </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="shell">bin/process-docs.sh</code></pre> </div> </div> <div class="paragraph"> The generated documentation can be found at <code>target/docs/htmlsingle/recipes</code>. This process can be long on the first run of the documentation as it is generating all of the documentation locally (e.g. reference documentation, tutorials, etc). To generate just the recipes, follow this process: </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="shell">bin/process-docs.sh -f docs/src/recipes</code></pre> </div> </div> <div class="paragraph"> The <code>bin/process-docs.sh</code> approach requires that Hadoop is installed. To avoid that prerequisite, try using Docker: </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="shell">docker/build.sh -d</code></pre> </div> </div> <div class="paragraph"> The downside to using Docker is that the process will take longer as each run will require the entire documentation set to be generated. </div> <div class="paragraph"> The final step to submitting a recipe is to issue a <a href="https://help.github.com/articles/using-pull-requests/">pull request through GitHub</a>. It is helpful to prefix the name of the pull request with the JIRA issue number, so that TinkerPop’s automation between GitHub and JIRA are linked. As mentioned earlier in this section, the recipe will go under review by TinkerPop committers prior to merging. This process may take several days to complete. We look forward to receiving your submissions! </div> </div> </div> <h1 id="_appendix" class="sect0">Appendix</h1> <div class="openblock partintro"> <div class="content"> <div class="paragraph"> Many of the recipes are based on questions and answers provided on the <a href="https://groups.google.com/forum/#!forum/gremlin-users">gremlin-users mailing list</a> or on <a href="http://stackoverflow.com/questions/tagged/gremlin">StackOverflow</a>. This section contains those traversals from those sources that do not easily fit any particular pattern (i.e. a recipe), but are nonetheless interesting and thus remain good tools for learning Gremlin. </div> <div id="appendix-a" class="paragraph"> For each person in a "follows" graph, determine the number of followers and list their names. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-1" type="radio" name="radio-set-1729796948-1" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-1" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-2" type="radio" name="radio-set-1729796948-1" class="tab-selector-2" /> <label for="tab-1729796948-2" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property('name','marko').as('marko'). addV().property('name','josh').as('josh'). addV().property('name','daniel').as('daniel'). addV().property('name','matthias').as('matthias'). addE('follows').from('josh').to('marko'). addE('follows').from('matthias').to('josh'). addE('follows').from('daniel').to('josh'). addE('follows').from('daniel').to('marko').iterate() gremlin> g.V().as('p'). map(__.in('follows').values('name').fold()). project('person','followers','numFollowers'). by(select('p').by('name')). by(). by(count(local)) ==>[person:marko,followers:[josh,daniel],numFollowers:2] ==>[person:josh,followers:[matthias,daniel],numFollowers:2] ==>[person:daniel,followers:[],numFollowers:0] ==>[person:matthias,followers:[],numFollowers:0]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property('name','marko').as('marko'). addV().property('name','josh').as('josh'). addV().property('name','daniel').as('daniel'). addV().property('name','matthias').as('matthias'). addE('follows').from('josh').to('marko'). addE('follows').from('matthias').to('josh'). addE('follows').from('daniel').to('josh'). addE('follows').from('daniel').to('marko').iterate() g.V().as('p'). map(__.in('follows').values('name').fold()). project('person','followers','numFollowers'). by(select('p').by('name')). by(). by(count(local))</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> It might also be alternatively written as: </div> <section class="tabs tabs-2"> <input id="tab-1729796948-3" type="radio" name="radio-set-1729796948-3" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-3" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-4" type="radio" name="radio-set-1729796948-3" class="tab-selector-2" /> <label for="tab-1729796948-4" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().group(). by('name'). by(project('numFollowers','followers'). by(__.in('follows').count()). by(__.in('follows').values('name').fold())).next() ==>daniel={numFollowers=0, followers=[]} ==>matthias={numFollowers=0, followers=[]} ==>josh={numFollowers=2, followers=[matthias, daniel]} ==>marko={numFollowers=2, followers=[josh, daniel]}</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().group(). by('name'). by(project('numFollowers','followers'). by(__.in('follows').count()). by(__.in('follows').values('name').fold())).next()</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> or even: </div> <section class="tabs tabs-2"> <input id="tab-1729796948-5" type="radio" name="radio-set-1729796948-5" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-5" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-6" type="radio" name="radio-set-1729796948-5" class="tab-selector-2" /> <label for="tab-1729796948-6" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().group(). by('name'). by(__.in('follows').values('name').fold(). project('numFollowers','followers'). by(count(local)). by()).next() ==>daniel={numFollowers=0, followers=[]} ==>matthias={numFollowers=0, followers=[]} ==>josh={numFollowers=2, followers=[matthias, daniel]} ==>marko={numFollowers=2, followers=[josh, daniel]}</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().group(). by('name'). by(__.in('follows').values('name').fold(). project('numFollowers','followers'). by(count(local)). by()).next()</code></pre> </div> </div> </div> </div> </section> <div id="appendix-b" class="paragraph"> In the "modern" graph, show each person, the software they worked on and the co-worker count for the software and the names of those co-workers. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-7" type="radio" name="radio-set-1729796948-7" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-7" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-8" type="radio" name="radio-set-1729796948-7" class="tab-selector-2" /> <label for="tab-1729796948-8" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().hasLabel("person").as("p"). out("created").as("s"). map(__.in("created"). where(neq("p")).values("name").fold()). group().by(select("p").by("name")). by(group().by(select("s").by("name")). by(project("numCoworkers","coworkers"). by(count(local)).by())).next() ==>peter={lop={numCoworkers=2, coworkers=[marko, josh]}} ==>josh={ripple={numCoworkers=0, coworkers=[]}, lop={numCoworkers=2, coworkers=[marko, peter]}} ==>marko={lop={numCoworkers=2, coworkers=[josh, peter]}}</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().hasLabel("person").as("p"). out("created").as("s"). map(__.in("created"). where(neq("p")).values("name").fold()). group().by(select("p").by("name")). by(group().by(select("s").by("name")). by(project("numCoworkers","coworkers"). by(count(local)).by())).next()</code></pre> </div> </div> </div> </div> </section> <div id="appendix-c" class="paragraph"> Assuming a graph of students, classes and times, detect students who have a conflicting schedule. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-9" type="radio" name="radio-set-1729796948-9" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-9" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-10" type="radio" name="radio-set-1729796948-9" class="tab-selector-2" /> <label for="tab-1729796948-10" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV("student").property("name", "Pete").as("s1"). addV("student").property("name", "Joe").as("s2"). addV("class").property("name", "Java's GC").as("c1"). addV("class").property("name", "FP Principles").as("c2"). addV("class").property("name", "Memory Management in C").as("c3"). addV("class").property("name", "Memory Management in C++").as("c4"). addV("timeslot").property("date", "11/25/2016").property("fromTime", "10:00").property("toTime", "11:00").as("t1"). addV("timeslot").property("date", "11/25/2016").property("fromTime", "11:00").property("toTime", "12:00").as("t2"). addE("attends").from("s1").to("c1"). addE("attends").from("s1").to("c2"). addE("attends").from("s1").to("c3"). addE("attends").from("s1").to("c4"). addE("attends").from("s2").to("c2"). addE("attends").from("s2").to("c3"). addE("allocated").from("c1").to("t1"). addE("allocated").from("c1").to("t2"). addE("allocated").from("c2").to("t1"). addE("allocated").from("c3").to("t2"). addE("allocated").from("c4").to("t2").iterate() gremlin> g.V().hasLabel("student").as("s"). out("attends").as("c"). out("allocated").as("t"). select("s"). out("attends"). where(neq("c")). out("allocated"). where(eq("t")). group(). by(select("s").by("name")). by(group().by(select("t").by(elementMap("fromTime","toTime"))). by(select("c").dedup().values("name").fold())).next() ==>Pete={{id=12, label=timeslot, fromTime=10:00, toTime=11:00}=[Java's GC, FP Principles], {id=16, label=timeslot, fromTime=11:00, toTime=12:00}=[Memory Management in C, Memory Management in C++, Java's GC]}</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV("student").property("name", "Pete").as("s1"). addV("student").property("name", "Joe").as("s2"). addV("class").property("name", "Java's GC").as("c1"). addV("class").property("name", "FP Principles").as("c2"). addV("class").property("name", "Memory Management in C").as("c3"). addV("class").property("name", "Memory Management in C++").as("c4"). addV("timeslot").property("date", "11/25/2016").property("fromTime", "10:00").property("toTime", "11:00").as("t1"). addV("timeslot").property("date", "11/25/2016").property("fromTime", "11:00").property("toTime", "12:00").as("t2"). addE("attends").from("s1").to("c1"). addE("attends").from("s1").to("c2"). addE("attends").from("s1").to("c3"). addE("attends").from("s1").to("c4"). addE("attends").from("s2").to("c2"). addE("attends").from("s2").to("c3"). addE("allocated").from("c1").to("t1"). addE("allocated").from("c1").to("t2"). addE("allocated").from("c2").to("t1"). addE("allocated").from("c3").to("t2"). addE("allocated").from("c4").to("t2").iterate() g.V().hasLabel("student").as("s"). out("attends").as("c"). out("allocated").as("t"). select("s"). out("attends"). where(neq("c")). out("allocated"). where(eq("t")). group(). by(select("s").by("name")). by(group().by(select("t").by(elementMap("fromTime","toTime"))). by(select("c").dedup().values("name").fold())).next()</code></pre> </div> </div> </div> </div> </section> <div id="appendix-d" class="paragraph"> In the "modern" graph, with a duplicate edge added, find the vertex pairs that have more than one edge between them. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-11" type="radio" name="radio-set-1729796948-11" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-11" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-12" type="radio" name="radio-set-1729796948-11" class="tab-selector-2" /> <label for="tab-1729796948-12" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(1).as("a").V(3).addE("created").property("weight",0.4d).from("a").iterate() gremlin> g.V(1).outE("created") ==>e[0][1-created->3] ==>e[9][1-created->3] gremlin> g.V().as("a"). out().as("b"). groupCount(). by(select("a","b")). unfold(). filter(select(values).is(gt(1))). select(keys) ==>[a:v[1],b:v[3]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(1).as("a").V(3).addE("created").property("weight",0.4d).from("a").iterate() g.V(1).outE("created") g.V().as("a"). out().as("b"). groupCount(). by(select("a","b")). unfold(). filter(select(values).is(gt(1))). select(keys)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> The following example assumes that the edges point in the <code>OUT</code> direction. Assuming undirected edges: </div> <section class="tabs tabs-2"> <input id="tab-1729796948-13" type="radio" name="radio-set-1729796948-13" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-13" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-14" type="radio" name="radio-set-1729796948-13" class="tab-selector-2" /> <label for="tab-1729796948-14" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().where(without("x")).as("a"). outE().as("e").inV().as("b"). filter(bothE().where(neq("e")).otherV().where(eq("a"))).aggregate(local, "x"). select("a","b").dedup()</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().where(without("x")).as("a"). outE().as("e").inV().as("b"). filter(bothE().where(neq("e")).otherV().where(eq("a"))).aggregate(local, "x"). select("a","b").dedup()</code></pre> </div> </div> </div> </div> </section> <div id="appendix-e" class="paragraph"> In the "crew" graph, find vertices that match on a complete set of multi-properties. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-15" type="radio" name="radio-set-1729796948-15" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-15" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-16" type="radio" name="radio-set-1729796948-15" class="tab-selector-2" /> <label for="tab-1729796948-16" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> places = ["centreville","dulles"];[] // will not match as "purcellville" is missing gremlin> g.V().not(has("location", without(places))). where(values("location").is(within(places)).count().is(places.size())). elementMap() gremlin> places = ["centreville","dulles","purcellville"];[] gremlin> g.V().not(has("location", without(places))). where(values("location").is(within(places)).count().is(places.size())). elementMap() ==>[id:7,label:person,name:stephen,location:purcellville]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">places = ["centreville","dulles"];[] // will not match as "purcellville" is missing g.V().not(has("location", without(places))). where(values("location").is(within(places)).count().is(places.size())). elementMap() places = ["centreville","dulles","purcellville"];[] g.V().not(has("location", without(places))). where(values("location").is(within(places)).count().is(places.size())). elementMap()</code></pre> </div> </div> </div> </div> </section> <div id="appendix-f" class="paragraph"> Methods for performing some basic mathematical operations in the "modern" graph. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-17" type="radio" name="radio-set-1729796948-17" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-17" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-18" type="radio" name="radio-set-1729796948-17" class="tab-selector-2" /> <label for="tab-1729796948-18" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().values("age").sum() // sum all ages ==>123 gremlin> g.V().values("age").fold(1, mult) // multiply all ages ==>876960 gremlin> g.withSack(0).V().values("age").sack(sum).sack(sum).by(constant(-1)).sack() // subtract 1 ==>28 ==>26 ==>31 ==>34 gremlin> g.withSack(0).V().values("age").sack(sum).sack(sum).sack() // multiply by 2 (simple) ==>58 ==>54 ==>64 ==>70 gremlin> g.withSack(0).V().values("age").sack(sum).sack(mult).by(constant(2)).sack() // multiply by 2 (generally useful for multiplications by n) ==>58 ==>54 ==>64 ==>70</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().values("age").sum() // sum all ages g.V().values("age").fold(1, mult) // multiply all ages g.withSack(0).V().values("age").sack(sum).sack(sum).by(constant(-1)).sack() // subtract 1 g.withSack(0).V().values("age").sack(sum).sack(sum).sack() // multiply by 2 (simple) g.withSack(0).V().values("age").sack(sum).sack(mult).by(constant(2)).sack() // multiply by 2 (generally useful for multiplications by n)</code></pre> </div> </div> </div> </div> </section> <div class="paragraph"> Method for doing a sum with division. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-19" type="radio" name="radio-set-1729796948-19" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-19" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-20" type="radio" name="radio-set-1729796948-19" class="tab-selector-2" /> <label for="tab-1729796948-20" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property(id, "a").as("a"). addV().property(id, "b").as("b"). addE("link").from("a").to("b"). addE("link").from("b").to("a"). addE("link").from("b").to("a").iterate() gremlin> g.withSack(0d). V("a").as("a"). V("b").as("b"). project("ab", "ba"). by(inE("link").where(outV().as("a")).count()). by(outE("link").where(inV().as("a")).count()). sack(sum).by("ab"). sack(div).by("ba"). project("a", "b", "#(a,b)", "#(b,a)", "#(a,b) / #(b,a)"). by(select("a")). by(select("b")). by("ab"). by("ba"). by(sack()) ==>[a:v[a],b:v[b],#(a,b):1,#(b,a):2,#(a,b) / #(b,a):0.5]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property(id, "a").as("a"). addV().property(id, "b").as("b"). addE("link").from("a").to("b"). addE("link").from("b").to("a"). addE("link").from("b").to("a").iterate() g.withSack(0d). V("a").as("a"). V("b").as("b"). project("ab", "ba"). by(inE("link").where(outV().as("a")).count()). by(outE("link").where(inV().as("a")).count()). sack(sum).by("ab"). sack(div).by("ba"). project("a", "b", "#(a,b)", "#(b,a)", "#(a,b) / #(b,a)"). by(select("a")). by(select("b")). by("ab"). by("ba"). by(sack())</code></pre> </div> </div> </div> </div> </section> <div id="appendix-g" class="paragraph"> Dropping a vertex, as well as the vertices related to that dropped vertex that are connected by a "knows" edge in the "modern" graph </div> <section class="tabs tabs-2"> <input id="tab-1729796948-21" type="radio" name="radio-set-1729796948-21" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-21" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-22" type="radio" name="radio-set-1729796948-21" class="tab-selector-2" /> <label for="tab-1729796948-22" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V().has('name','marko').outE() ==>e[9][1-created->3] ==>e[7][1-knows->2] ==>e[8][1-knows->4] gremlin> g.V().has('name','marko').sideEffect(out('knows').drop()).drop() gremlin> g.V().has('name','marko') gremlin> g.V(2,4,3) ==>v[3]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V().has('name','marko').outE() g.V().has('name','marko').sideEffect(out('knows').drop()).drop() g.V().has('name','marko') g.V(2,4,3)</code></pre> </div> </div> </div> </div> </section> <div id="appendix-h" class="paragraph"> For the specified graph, find all neighbor vertices connected to "A" as filtered by datetime, those neighbor vertices that don’t have datetime vertices, and those neighbor vertices that have the label "dimon". </div> <section class="tabs tabs-2"> <input id="tab-1729796948-23" type="radio" name="radio-set-1729796948-23" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-23" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-24" type="radio" name="radio-set-1729796948-23" class="tab-selector-2" /> <label for="tab-1729796948-24" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV().property("name", "A").as("a"). addV().property("name", "B").as("b"). addV().property("name", "C").as("c"). addV().property("name", "D").as("d"). addV().property("name", "E").as("e"). addV("dimon").property("name", "F").as("f"). addV().property("name", "G").as("g").property("date", 20160818). addV().property("name", "H").as("h").property("date", 20160817). addE("rel").from("a").to("b"). addE("rel").from("a").to("c"). addE("rel").from("a").to("d"). addE("rel").from("a").to("e"). addE("rel").from("c").to("f"). addE("occured_at").from("d").to("g"). addE("occured_at").from("e").to("h").iterate() gremlin> // D and E have a valid datetime ==>true gremlin> g.V().has("name", "A").out("rel"). union(where(out("occured_at").has("date", gte(20160817))), __.not(outE("occured_at")).coalesce(out().hasLabel("dimon"), identity())). elementMap() ==>[id:2,label:vertex,name:B] ==>[id:10,label:dimon,name:F] ==>[id:6,label:vertex,name:D] ==>[id:8,label:vertex,name:E] gremlin> // only E has a valid date ==>true gremlin> g.V().has("name", "A").out("rel"). union(where(out("occured_at").has("date", lte(20160817))), __.not(outE("occured_at")).coalesce(out().hasLabel("dimon"), identity())). elementMap() ==>[id:2,label:vertex,name:B] ==>[id:10,label:dimon,name:F] ==>[id:8,label:vertex,name:E] gremlin> // only D has a valid date ==>true gremlin> g.V().has("name", "A").out("rel"). union(where(out("occured_at").has("date", gt(20160817))), __.not(outE("occured_at")).coalesce(out().hasLabel("dimon"), identity())). elementMap() ==>[id:2,label:vertex,name:B] ==>[id:10,label:dimon,name:F] ==>[id:6,label:vertex,name:D] gremlin> // neither D nor E have a valid date ==>true gremlin> g.V().has("name", "A").out("rel"). union(where(out("occured_at").has("date", lt(20160817))), __.not(outE("occured_at")).coalesce(out().hasLabel("dimon"), identity())). elementMap() ==>[id:2,label:vertex,name:B] ==>[id:10,label:dimon,name:F]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV().property("name", "A").as("a"). addV().property("name", "B").as("b"). addV().property("name", "C").as("c"). addV().property("name", "D").as("d"). addV().property("name", "E").as("e"). addV("dimon").property("name", "F").as("f"). addV().property("name", "G").as("g").property("date", 20160818). addV().property("name", "H").as("h").property("date", 20160817). addE("rel").from("a").to("b"). addE("rel").from("a").to("c"). addE("rel").from("a").to("d"). addE("rel").from("a").to("e"). addE("rel").from("c").to("f"). addE("occured_at").from("d").to("g"). addE("occured_at").from("e").to("h").iterate() // D and E have a valid datetime g.V().has("name", "A").out("rel"). union(where(out("occured_at").has("date", gte(20160817))), __.not(outE("occured_at")).coalesce(out().hasLabel("dimon"), identity())). elementMap() // only E has a valid date g.V().has("name", "A").out("rel"). union(where(out("occured_at").has("date", lte(20160817))), __.not(outE("occured_at")).coalesce(out().hasLabel("dimon"), identity())). elementMap() // only D has a valid date g.V().has("name", "A").out("rel"). union(where(out("occured_at").has("date", gt(20160817))), __.not(outE("occured_at")).coalesce(out().hasLabel("dimon"), identity())). elementMap() // neither D nor E have a valid date g.V().has("name", "A").out("rel"). union(where(out("occured_at").has("date", lt(20160817))), __.not(outE("occured_at")).coalesce(out().hasLabel("dimon"), identity())). elementMap()</code></pre> </div> </div> </div> </div> </section> <div id="appendix-i" class="paragraph"> Use element labels in a <code>select</code>. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-25" type="radio" name="radio-set-1729796948-25" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-25" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-26" type="radio" name="radio-set-1729796948-25" class="tab-selector-2" /> <label for="tab-1729796948-26" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.V(1).as("a"). both(). map(group().by(label).by(unfold())).as("b"). select("a","b"). map(union(project("a").by(select("a")), select("b")). unfold(). group(). by(select(keys)). by(select(values))) ==>[a:v[1],software:v[3]] ==>[a:v[1],person:v[2]] ==>[a:v[1],person:v[4]] gremlin> g.V().as("a"). both(). map(group().by(label).by(unfold())).as("b"). select("a","b"). group(). by("a"). by(select("b"). group(). by(select(keys)). by(select(values).fold())). unfold(). map(union(select(keys).project("a").by(), select(values)). unfold(). group(). by(select(keys).unfold()). by(select(values).unfold().unfold().fold())) ==>[a:[v[1]],software:[v[3]],person:[v[2],v[4]]] ==>[a:[v[2]],person:[v[1]]] ==>[a:[v[3]],person:[v[1],v[4],v[6]]] ==>[a:[v[4]],software:[v[5],v[3]],person:[v[1]]] ==>[a:[v[5]],person:[v[4]]] ==>[a:[v[6]],software:[v[3]]]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.V(1).as("a"). both(). map(group().by(label).by(unfold())).as("b"). select("a","b"). map(union(project("a").by(select("a")), select("b")). unfold(). group(). by(select(keys)). by(select(values))) g.V().as("a"). both(). map(group().by(label).by(unfold())).as("b"). select("a","b"). group(). by("a"). by(select("b"). group(). by(select(keys)). by(select(values).fold())). unfold(). map(union(select(keys).project("a").by(), select(values)). unfold(). group(). by(select(keys).unfold()). by(select(values).unfold().unfold().fold()))</code></pre> </div> </div> </div> </div> </section> <div id="appendix-j" class="paragraph"> Sum edge weight with a coefficient. </div> <section class="tabs tabs-2"> <input id="tab-1729796948-27" type="radio" name="radio-set-1729796948-27" class="tab-selector-1" checked="checked" /> <label for="tab-1729796948-27" class="tab-label-1">console (groovy)</label> <input id="tab-1729796948-28" type="radio" name="radio-set-1729796948-27" class="tab-selector-2" /> <label for="tab-1729796948-28" class="tab-label-2">groovy</label> <div class="tabcontent"> <div class="tabcontent-1"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">gremlin> g.addV('person').property('name','alice').as('alice'). addV('person').property('name','bobby').as('bobby'). addV('person').property('name','cindy').as('cindy'). addV('person').property('name','david').as('david'). addV('person').property('name','eliza').as('eliza'). addE('rates').from('alice').to('bobby').property('tag','ruby').property('value',9). addE('rates').from('bobby').to('cindy').property('tag','ruby').property('value',8). addE('rates').from('cindy').to('david').property('tag','ruby').property('value',7). addE('rates').from('david').to('eliza').property('tag','ruby').property('value',6). addE('rates').from('alice').to('eliza').property('tag','java').property('value',9).iterate() gremlin> g.withSack(1.0).V().has("name","alice"). repeat(outE("rates").has("tag","ruby"). project("a","b","c"). by(inV()). by(sack()). by("value").as("x"). select("a"). sack(mult).by(constant(0.5))). times(3).emit(). select(all, "x"). project("name","score"). by(tail(local, 1).select("a").values("name")). by(unfold(). sack(assign).by(select("b")). sack(mult).by(select("c")). sack().sum()) ==>[name:bobby,score:9.0] ==>[name:cindy,score:13.00] ==>[name:david,score:14.750]</code></pre> </div> </div> </div> </div> <div class="tabcontent"> <div class="tabcontent-2"> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="groovy">g.addV('person').property('name','alice').as('alice'). addV('person').property('name','bobby').as('bobby'). addV('person').property('name','cindy').as('cindy'). addV('person').property('name','david').as('david'). addV('person').property('name','eliza').as('eliza'). addE('rates').from('alice').to('bobby').property('tag','ruby').property('value',9). addE('rates').from('bobby').to('cindy').property('tag','ruby').property('value',8). addE('rates').from('cindy').to('david').property('tag','ruby').property('value',7). addE('rates').from('david').to('eliza').property('tag','ruby').property('value',6). addE('rates').from('alice').to('eliza').property('tag','java').property('value',9).iterate() g.withSack(1.0).V().has("name","alice"). repeat(outE("rates").has("tag","ruby"). project("a","b","c"). by(inV()). by(sack()). by("value").as("x"). select("a"). sack(mult).by(constant(0.5))). times(3).emit(). select(all, "x"). project("name","score"). by(tail(local, 1).select("a").values("name")). by(unfold(). sack(assign).by(select("b")). sack(mult).by(select("c")). sack().sum())</code></pre> </div> </div> </div> </div> </section> </div> </div> </div> <div id="footer"> <div id="footer-text"> Last updated 2024-10-24 12:31:41 -0700 </div> </div> </body> </html>