ai.grakn.graql.ComputeQuery Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of grakn-core Show documentation
There is a newer version: 1.4.3
/*
 * GRAKN.AI - THE KNOWLEDGE GRAPH
 * Copyright (C) 2018 Grakn Labs Ltd
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see .
 */

package ai.grakn.graql;

import ai.grakn.GraknTx;
import ai.grakn.concept.ConceptId;
import ai.grakn.concept.Label;
import ai.grakn.exception.GraqlQueryException;
import ai.grakn.graql.answer.Answer;

import javax.annotation.CheckReturnValue;
import java.util.Collection;
import java.util.Optional;
import java.util.Set;

import static ai.grakn.util.GraqlSyntax.Compute.Algorithm;
import static ai.grakn.util.GraqlSyntax.Compute.Argument;
import static ai.grakn.util.GraqlSyntax.Compute.Method;
import static ai.grakn.util.GraqlSyntax.Compute.Parameter;

/**
 * Graql Compute Query: to perform distributed analytics OLAP computation on Grakn
 * @param  return type of ComputeQuery
 */
public interface ComputeQuery extends Query {

    /**
     * @param tx the graph to execute the compute query on
     * @return a ComputeQuery with the graph set
     */
    @Override
    ComputeQuery withTx(GraknTx tx);

    /**
     * @param fromID is the Concept ID of in which compute path query will start from
     * @return A ComputeQuery with the fromID set
     */
    ComputeQuery from(ConceptId fromID);

    /**
     * @return a String representing the name of the compute query method
     */
    Method method();

    /**
     * @return a Concept ID in which which compute query will start from
     */
    @CheckReturnValue
    Optional from();

    /**
     * @param toID is the Concept ID in which compute query will stop at
     * @return A ComputeQuery with the toID set
     */
    ComputeQuery to(ConceptId toID);

    /**
     * @return a Concept ID in which which compute query will stop at
     */
    @CheckReturnValue
    Optional to();

    /**
     * @param types is an array of concept types in which the compute query would apply to
     * @return a ComputeQuery with the of set
     */
    ComputeQuery of(String type, String... types);

    /**
     * @param types is an array of concept types in which the compute query would apply to
     * @return a ComputeQuery with the of set
     */
    ComputeQuery of(Collection types);

    /**
     * @return the collection of concept types in which the compute query would apply to
     */
    @CheckReturnValue
    Optional> of();

    /**
     * @param types is an array of concept types that determines the scope of graph for the compute query
     * @return a ComputeQuery with the inTypes set
     */
    ComputeQuery in(String type, String... types);

    /**
     * @param types is an array of concept types that determines the scope of graph for the compute query
     * @return a ComputeQuery with the inTypes set
     */
    ComputeQuery in(Collection types);

    /**
     * @return the collection of concept types that determines the scope of graph for the compute query
     */
    @CheckReturnValue
    Optional> in();

    /**
     * @param algorithm name as an condition for the compute query
     * @return a ComputeQuery with algorithm condition set
     */
    ComputeQuery using(Algorithm algorithm);

    /**
     * @return the algorithm type for the compute query
     */
    @CheckReturnValue
    Optional using();

    /**
     * @param arg  is an argument that could provided to modify the compute query parameters
     * @param args is an array of arguments
     * @return a ComputeQuery with the arguments set
     */
    ComputeQuery where(Argument arg, Argument... args);

    /**
     * @param args is a list of arguments that could be provided to modify the compute query parameters
     * @return
     */
    ComputeQuery where(Collection args);

    /**
     * @return an Arguments object containing all the provided individual arguments combined
     */
    @CheckReturnValue
    Optional where();

    /**
     * Allow analytics query to include attributes and their relationships
     *
     * @return a ComputeQuery with the inTypes set
     */
    ComputeQuery includeAttributes(boolean include);

    /**
     * Get if this query will include attributes and their relationships
     */
    @CheckReturnValue
    boolean includesAttributes();

    /**
     * @return a boolean representing whether this query is a valid Graql Compute query given the provided conditions
     */
    @CheckReturnValue
    boolean isValid();

    /**
     * @return any exception if the query is invalid
     */
    @CheckReturnValue
    Optional getException();

    /**
     * Checks Whether this query will modify the graph
     */
    @Override
    default boolean isReadOnly() {
        return true;
    }

    /**
     * kill the compute query, terminate the job
     */
    void kill();


    /**
     * Argument inner interface to provide access Compute Query arguments
     *
     * @author Grakn Warriors
     */
    interface Arguments {

        @CheckReturnValue
        Optional getArgument(Parameter param);

        @CheckReturnValue
        Collection getParameters();

        @CheckReturnValue
        Optional minK();

        @CheckReturnValue
        Optional k();

        @CheckReturnValue
        Optional size();

        @CheckReturnValue
        Optional contains();
    }

}